Beaker setup 是一个面向 Python 仓库的 Beaker Integration 接入技能，用途是把仓库内真实的 LLM 或智能体任务转成仓库优化集成。它要求先发现应用入口、候选源文件、模型调用、评分器和带标签数据，再完成接入，并在存在真实标注样本时以本地结构冒烟检查收尾；仅在开发者明确要求时才远程启动。
版本检查方面，该技能 0.6.5 对应 beaker-sdk 0.6.5，两者按相同版本号同步发布，出现任何版本差异即表示有一侧过旧。开始正常流程前运行 beaker --version（或在项目中尚未安装 Beaker 时运行 uvx --from 'beaker-sdk>=0.6.5' beaker --version）。若已安装的 CLI 低于 0.6.5，或不识别 --version，应通过项目的开发依赖流程升级 beaker-sdk 后再继续；若 CLI 高于 0.6.5，则说明技能过旧，运行 npx skills update beaker-setup 与 npx skills update beaker-usage，然后按前述方式重新加载技能，不要靠猜测 CLI 行为来绕过版本不匹配。
主要流程按顺序执行：先运行 beaker auth status（仅在失败时运行 beaker login），再运行 beaker agent list --json；在项目依赖尚未安装前，用 uvx --from beaker-sdk beaker ... 调用。随后识别真正被优化的包或服务，而不是 Git 根目录——在 monorepo 中即包含该任务自身 pyproject.toml 的目录。接着选择该项目已有的 Beaker 配置，或进入项目根目录运行 beaker init。生成后应立即检查 integrations.<id>.source_dir，它必须是相对 Git 根目录的项目目录（例如 services/invoices），仅当项目本身就是 Git 根时才是 "."，若不一致应立即修正。然后把 beaker init 输出的 beaker-sdk 依赖安装命令装进项目的开发/工具依赖组。
在初步发现后，应把当前已知的未决问题一并提出，例如优化哪个指标、标注数据来源、快速开始还是完整数据集规模、agent 名称、judge 模型或所需凭据；同时继续独立发现与实现，不必等待发现穷尽。随后替换集成中所有 TODO(beaker) 并接入真实模型调用，运行 beaker agent setup "<Agent Name>"（配置含多个集成时加 --integration-id <id>），该命令会把 agent key 写入 integrations.<id>.agent_key。上传或选择标注数据集后，保留其不可变的 name@revision 或 artifact id，并把同一选择器显式传给 smoke 与 launch，确认所需托管环境变量，用 beaker run smoke --strict 验证。
提交与推送方面，应在所选配置与数据集定稿后提交并推送一次到 beaker/<YYYYMMDD-HHMM>-<agent-name> 分支；首次托管运行使用 beaker run trigger（包含 Beaker agent、dataset、可选 --ref 以及适用时必需的 judge 配置）。除非开发者明确要求比较特定模型，否则不要传 --optimization-model。整个过程中，beaker onboarding status 是设置循环的控制命令：在完成一个 onboarding 步骤后运行，并严格按其返回的单一 next action 执行；若返回 blocked_on_developer 列表，只把新发现的开发者负责动作原样转达并请其立即开始，同时继续自身工作。
隔离要求方面，Beaker 应被视为开发/评估工具而非应用运行时：配置文件、集成、辅助代码、凭据、gitignore 与 trace 记录尽量都放在所选项目的 .beaker/ 下；不新增 Beaker 模块到应用包、不从生产入口导入或初始化 Beaker、不改部署/运行时配置、不新增或修改测试与 CI/CD、不让正常流量经过 Beaker。仅允许少数例外：保留原位置的数据集；只读方式阅读现有测试作为证据；在支持分离的项目中记录到开发/工具依赖元数据及锁文件；仅当 .beaker/ 下的集成与辅助代码无法复用既有接口时，添加最小的可选应用注入缝隙，并保持生产默认行为一致。
该技能明确不编写测试代码与 CI/CD 接线（包括 GitHub Actions 等流水线、pre-commit 钩子、Makefile 目标、任务运行器条目或自动运行 Beaker 的脚本），也不在 onboarding 期间运行仓库测试套件；集成由 beaker run smoke --strict 与托管运行来验证。允许对改动文件运行仓库既有 linter、formatter 或类型检查。若开发者明确要求测试或流水线任务，则只构建其要求的部分。此外，在集成推送时绝不推送到 main、master 或仓库默认分支，也绝不打开 PR，除非开发者要求；只暂存集成相关文件，绝不暂存任何密钥文件，并报告所推送的分支。