skill-optimizer

Skill Optimizer

自进化的 skill 优化。将 SKILL.md 视为冻结 Agent 的可训练参数。经验证门控、预算上限约束、原子化版本管理。

基于 SkillOpt（arXiv 2605.23904，Microsoft Research，2026 年 5 月）。

何时调用此 skill

用户希望：

• 针对基准测试提升现有 skill 的执行质量
• 为新 skill 引导生成基准测试文件
• 切换目标模型后重新调优 skill

铁律

• 验证门控是强制的。 每个候选方案在覆盖 SKILL.md 之前，必须在 sel-set 上以中位数（3 次运行）加 epsilon=0.05 的余量通过验证。
• 禁止修改 frontmatter。 优化器只编辑正文。路由层（triggers:、brain_first:）保持不变。
• 内置 skill 需要明确授权，并且需要独立的留出集。 随 gbrain 发布的 skill 不能被自动修改。若要原地重写，用户必须同时传入 --allow-mutate-bundled 和 --held-out <path>，且留出集至少包含 5 个与基准任务互不重叠的任务；若缺少留出集，运行将直接拒绝并以退出码 2 结束。若去掉 --allow-mutate-bundled（或传入 --no-mutate，即 dream-cycle 阶段的默认值），则会改为写入 proposed.md 供审阅，仅用于审阅的输出无需留出集。
• 引导生成的输出需要人工审阅。 --bootstrap-from-skill 和 --bootstrap-from-routing 都会写入一个哨兵文件；你必须审阅并加强生成的评判器，删除该哨兵文件，然后使用 --bootstrap-reviewed 重新运行，优化流程才能使用该文件。

流程

gbrain skillopt <skill-name> [flags]
  │
  ├── Pre-flight gates
  │     ├── working tree clean (or --force)
  │     ├── benchmark valid + D_sel >= 5 (D17)
  │     ├── cost preflight (D3) — refuses over --max-cost-usd
  │     └── per-skill DB lock (D14)
  │
  ├── Baseline eval on D_sel (sets best_sel_score)
  │
  ├── for epoch in 1..N:
  │     for step in 1..steps_per_epoch:
  │       ├── forward pass: rollouts on D_train batch
  │       ├── backward pass: reflect × 2 (failures + successes per D7)
  │       ├── rank + clip via LR cosine schedule
  │       ├── apply edits (body-only per D5, tagged result per D9)
  │       ├── validation gate: median-of-3 + epsilon=0.05 (D12)
  │       └── if accept: commit via D8 history-intent-first
  │     │
  │     └── slow update (D6) if no improvement this epoch
  │
  └── Final test eval on D_test → run receipt

你的 skill 存放位置

随插件捆绑发布的 skill 是只读快照，你无法在其旁边写入基准测试或优化产物。请针对你自己的可写 skill 目录运行 skillopt：传入 --skills-dir <path>（gbrain skillopt X --skills-dir ~/my-project/skills），或在包含 skills/ 目录树的工作区中运行，命令行工具会自动检测该目录。下文中所有 skills/X/... 路径均指该可写目录（即你自己编写的 skill、由 skillify 生成脚手架的 skill，或驻留在 brain 中的 skillpack），而非插件快照。

从 Skill 本身开始创建基准（常见情况）

用户不会手写基准，你也不应从空白文件开始。 当用户说"让 skill X 更好"且 skills/X/skillopt-benchmark.jsonl 不存在时，请直接根据 SKILL.md 生成一个初始版本：

1. 生成初始版本。 运行：

   gbrain skillopt X --bootstrap-from-skill
   

   一次 LLM 调用会读取 skills/X/SKILL.md，推断该 skill 产出什么以及什么是"好"的结果，并将约 15 个任务（每个任务附带规则判定器）写入 skills/X/skillopt-benchmark.jsonl，同时加上一行 # BOOTSTRAP_PENDING_REVIEW 标记。不需要 routing-eval.jsonl。可用 --bootstrap-tasks N 调整数量（最多 50）。
2. 审查并加强判定器。 这是你的工作，且至关重要。生成的规则检查只是粗略草稿，模型往往会输出泛泛的 contains、宽松的 max_chars，或是凭空编造的标题。请逐个阅读任务，修正软性检查，并添加该 skill 真正要求的必备项（真实的章节名称、真实的长度上限、在需要来源时使用 min_citations，以及对 skill 确实会使用的工具使用 tool_called/tool_not_called）。单薄的基准只会优化出单薄的质量定义，不要不加审查就直接通过。
3. 删除标记行（# BOOTSTRAP_PENDING_REVIEW，即最后一行）。
4. 使用 --split 1:1:1 运行优化器：

   gbrain skillopt X --bootstrap-reviewed --split 1:1:1
   

   对于 15 个任务的初始版本，必须使用 1:1:1 划分。默认的 4:1:5 会使验证集大小为 floor(15/10)=1，低于 D_sel >= 5 的下限，优化器会以 d_sel_too_small 拒绝运行。（4:1:5 需要约 50 个任务。）请先加 --dry-run 预览成本。

基准行格式（生成器写入的每行内容）：

{"task_id":"x-001","task":"<user prompt>","judge":{"kind":"rule","checks":[{"op":"max_chars","arg":1800},{"op":"contains","arg":"agenda"}]}}

你将用来加强的规则检查词汇：contains、regex、section_present、max_chars、min_citations、tool_called、tool_not_called。规则判定器确定性强且免费，但对于质量取决于步骤顺序、隐私、拒绝边界或文件存放位置的 skill 来说，检查过于浅显。这类情况请在审查时手动添加更丰富的检查（或使用 llm 判定器）。

备选方案——手工编写。 如果生成的初始版本质量很差（罕见，但对于行为导向很强的 skill 可能出现），请舍弃它，自行编写 JSONL：阅读 SKILL.md，编写约 15 个覆盖常规中间情况的真实任务，每个任务附加至少 2 项规则检查，保存到 skills/X/skillopt-benchmark.jsonl，并使用 --split 1:1:1 运行。完整教程见 https://github.com/garrytan/gbrain/blob/master/docs/tutorials/improving-skills-with-skillopt.md。

决策树

情况	操作
Skill 没有基准	gbrain skillopt foo --bootstrap-from-skill → 审查并加强判定器 → 删除标记行 → gbrain skillopt foo --bootstrap-reviewed --split 1:1:1（见上文章节）
Skill 有 routing-eval.jsonl，想要快速起步	gbrain skillopt foo --bootstrap-from-routing → 审查生成的任务 → --bootstrap-reviewed（路由任务用于测试分发；在信任之前，需将其收紧为质量任务）
迭代已有的 skill	gbrain skillopt foo --benchmark skills/foo/skillopt-benchmark.jsonl
运行成本较高，想先预览	添加 --dry-run
内置 skill（gbrain 仓库中的 skills/）	默认写入 proposed.md；若要原地提交，需同时添加 --allow-mutate-bundled 和 --held-out <path>（≥5 个与基准不相交的任务），否则会直接拒绝。插件安装的 skill 无法原地修改内置 skill（快照为只读）：请将 SKILL.md 复制到你自己的 skills 目录中进行迭代，或沿用默认的 proposed.md 审阅流程
希望在应用前审阅更改	添加 --no-mutate（写入 proposed.md，无需 held-out 集）
防止基准过拟合	添加 --held-out <path>——若候选方案在基准上胜出，但在 held-out 集上表现倒退，则会被拒绝
运行中途崩溃	gbrain skillopt foo --resume <run-id>

输出格式

调用本技能时，会生成以下内容：

• 更新后的 skills/<name>/SKILL.md（允许修改时）
• skills/<name>/skillopt/best.md — 当前最优版本的指针副本
• skills/<name>/skillopt/versions/vNNNN_eN_sN.md — 每一步的快照
• skills/<name>/skillopt/history.json — 只追加的运行记录
• skills/<name>/skillopt/rejected.json — 有界 LRU 的被拒编辑记录
• ~/.gbrain/audit/skillopt-YYYY-Www.jsonl — 按 ISO 周轮转的审计日志

失败时的处理

遇到任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循Agent 操作协议。本技能特有的情况如下：

• 硬性拒绝：dirty_tree（先提交或暂存技能编辑）、d_sel_too_small（添加基准任务）、未带 --allow-mutate-bundled 却同时使用 --held-out 的内置技能（退出码 2）。请修正输入，切勿强行绕过。
• 成本预检超出 --max-cost-usd 时会拒绝执行；在用户设置上限的情况下出现 no_pricing 时，请先使用 --dry-run 预览，然后再询问用户是否提高上限。
• skill_candidate_invalid：候选版本修改了受保护的 frontmatter，或生成了空正文；应丢弃该候选版本并报告。

反模式

• 不要绕过验证闸门。 中位数取自 3 次运行并使用 epsilon=0.05，这一机制至关重要；缺少它，优化器会把噪声当作改进。
• 没有同时指定 --allow-mutate-bundled 和 --held-out 时，不要优化内置技能。 这些技能随 gbrain 一同发布，对下游 Agent 至关重要。原地修改必须同时使用两个标志（held-out 需要至少 5 个与基准互不重叠的任务）；若没有 held-out 集，运行会被硬性拒绝，并指向 proposed.md。
• 不要在未加强的情况下直接使用引导输出。 --bootstrap-from-skill 和 --bootstrap-from-routing 都会让优化器模型自行编造成功标准，默认情况下这些标准笼统且较弱。在 SkillOpt 据此优化之前，请先审查并收紧评判标准，否则它会把技能训练成迎合基准产物，而非真正的质量。
• 在约 15 个任务的入门集上，不要跳过 --split 1:1:1。 默认的 4:1:5 划分会使验证集低于 D_sel >= 5 的下限，运行将因 d_sel_too_small 而中止。

合约

runSkillOpt(opts) 返回：

{
  outcome: 'accepted' | 'no_improvement' | 'aborted' | 'errored',
  receipt: {
    run_id, skill_sha8, benchmark_sha8, models, cost,
    baseline_sel_score, best_sel_score,   // real measured baseline (no longer hardcoded 0)
    baseline_test_score, test_score,      // final held-out test-split eval
  },
  finalText: string,
  mutatedSkillFile: boolean,
  proposedPath?: string
}

相关技能

• skillify — 搭建新技能的脚手架（应在 skillopt 之前使用）
• skillpack-check — 审计技能合规性（第 13 项展示 skillopt 状态）
• conventions/quality.md — skillopt 通过评判器执行的输出质量标准