skill-creator — 造 skill 的元技能

本章讲什么: skill-creator 是仓库里唯一一个用来造别的 skill 的 skill。它的精华不在「怎么写 markdown」,而在怎么证明一个 skill 真的让 Claude 变强了——一套 with_skill vs baseline 的对照实验,加上一个把 description 触发率当指标来优化的循环。读完你会明白:好 skill 是测出来 + 迭代出来的,不是一次写对的。

1. 核心循环(先看全貌)

skill-creator 自己把整个流程总结成一句话级别的循环(skills/skill-creator/SKILL.md:10-20, 472-481):

①想清楚要做什么 → ②写/改 skill 草稿 → ③在测试 prompt 上跑 with-skill
        ▲                                          │
        │                                          ▼
   ⑤满意?否 ←──── ④和用户一起评测(定性看输出 + 定量看 benchmark)
        │ 是
        ▼
   打包成 .skill 交付

它强调「你的任务是判断用户走到了循环哪一步,然后接上去」——用户可能只说「我想做个 X 的 skill」(从①接),也可能已有草稿(直接从③接)。来源:skills/skill-creator/SKILL.md:22-26。

2. 写草稿阶段:三件容易被忽略的事

2.1 description 是触发器,要『推』

这点在 index §3 已点过,这里给出原话级别的依据。skill-creator 明确说 Claude 现在倾向漏触发,所以要把 description 写得「pushy」:

与其写 "How to build a simple fast dashboard…",不如写 "…Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"

来源:skills/skill-creator/SKILL.md:67。并且所有「何时用」的信息都进 description,不进正文(同行)。

2.2 写法上「解释为什么」,少用全大写 MUST

skill-creator 反复劝诫:今天的模型很聪明、有不错的 theory of mind,与其堆 ALWAYS/NEVER,不如解释清楚『为什么这步重要』。看到自己在写全大写 MUST 就是个黄灯,应该改成讲清缘由。来源:skills/skill-creator/SKILL.md:139(Writing Style)与「Improving the skill」第 3 条(:302)。

2.3 测试用例要像真人说的话

草稿后写 2-3 个真实用户会说的 prompt,存到 evals/evals.json(此时只写 prompt,不写断言)。来源:skills/skill-creator/SKILL.md:143-159。evals.json 的结构见 §5 schema。

3. 对照评测:整套实验的灵魂

这是 skill-creator 最有工程含量的部分:不是「跑一下看好不好」,而是做对照实验——同一个 prompt,一组带 skill、一组不带,比出 skill 到底贡献了多少。

3.1 同一轮里同时发起 with-skill 和 baseline

纪律很明确:对每个测试用例,在同一个 turn 里发两个 subagent——一个带 skill,一个不带。不能先把带 skill 的跑完再回头补 baseline,要一起发、一起完成。来源:skills/skill-creator/SKILL.md:169-171。

baseline 是谁,取决于场景:

场景	baseline	输出目录
造新 skill	完全不挂 skill	without_skill/outputs/
改进已有 skill	改之前先快照(cp -r),拿旧版当 baseline	old_skill/outputs/

来源:skills/skill-creator/SKILL.md:184-186。

3.2 工作区目录怎么组织

结果放在与 skill 同级的 <skill-name>-workspace/,按迭代再按用例分层,且用到才建,不要一上来全建:

<skill-name>-workspace/
└── iteration-1/
    ├── <descriptive-eval-name>/      ← 用描述性名字,不是裸 eval-0
    │   ├── with_skill/outputs/
    │   ├── without_skill/outputs/    ← (或改进场景下的 old_skill/)
    │   ├── eval_metadata.json
    │   ├── timing.json
    │   └── grading.json
    └── benchmark.json

来源:skills/skill-creator/SKILL.md:167-168, 188-197。

3.3 趁跑的时候补断言,别干等

run 在后台跑时,这段时间用来起草定量断言(assertions)并讲给用户听。好断言「可客观验证、名字有描述性」;主观技能(写作风格、设计美感)别硬塞断言,该靠人定性评。来源:skills/skill-creator/SKILL.md:199-205。

3.4 抓时延数据是「一次性机会」

一个易错点:subagent 完成时的通知里带 total_tokens 和 duration_ms,这是唯一一次能拿到它们的机会,别处不持久化——所以要立刻写进该 run 的 timing.json,逐条处理通知,别想着攒一批。来源:skills/skill-creator/SKILL.md:207-219。

3.5 评分 → 聚合 → 分析 → 给人看

全部跑完后四步(skills/skill-creator/SKILL.md:222-251):

1. 评分:让 grader subagent(读 agents/grader.md)逐条断言判过/不过,写 grading.json。能用脚本判的就写脚本判,别用眼睛瞪。
2. 聚合:python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>,产出带均值±标准差和 delta 的 benchmark.json / benchmark.md。
3. 分析师视角:读 benchmark,挖聚合数字盖住的模式——比如「不论带不带 skill 都 100% 过」的无区分度断言、高方差(可能 flaky)的 eval、时延/token 的取舍。
4. 开 viewer:用 eval-viewer/generate_review.py 给人看定性输出 + 定量对比,不要自己手写 HTML。

一句重话(原文级): skill-creator 在 Cowork 小节里全大写强调 「GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself」——先把结果摆到人面前,再自己去改。来源:skills/skill-creator/SKILL.md:451。

4. 改进的思路:别过拟合那几个例子

拿到反馈后怎么改,skill-creator 给了四条「思考法」(skills/skill-creator/SKILL.md:296-304),核心是别为眼前这 2-3 个测例做 fiddly 的过拟合修补:

• 从反馈里泛化:目标是造一个能被用百万次的 skill;只对手头例子有效 = 没用。卡住时换个比喻、换个工作模式试试,成本很低。
• 保持精简:读 transcript 不只读最终输出;若 skill 让模型浪费时间做无用功,就删掉那段看看。
• 解释为什么(同 §2.2)。
• 发现重复劳动就沉淀成脚本:如果三个测例的 subagent 都各自独立写了个 create_docx.py,这就是强信号——把它写一次放进 scripts/,让以后每次调用都省掉重造轮子。来源::304。

5. 数据结构:schema.json 契约

skill-creator 的评测体系靠几个 JSON 文件串起来,字段名是被 viewer 严格依赖的(写错就显示空/零)。最该记住的两个:

grading.json 的断言三件套

{
  "expectations": [
    {"text": "The output includes the name 'John Smith'",
     "passed": true,
     "evidence": "Found in transcript Step 3: 'Extracted names: John Smith…'"}
  ]
}

来源:skills/skill-creator/references/schemas.md「grading.json」(约 88-149 行)。SKILL.md 特别警告:必须用 text/passed/evidence 这三个字段名,别用 name/met/details——viewer 靠这些精确名字工作(skills/skill-creator/SKILL.md:225)。

benchmark.json 的 with_skill / without_skill 对照

{
  "run_summary": {
    "with_skill":    {"pass_rate": {"mean": 0.85, "stddev": 0.05}},
    "without_skill": {"pass_rate": {"mean": 0.35, "stddev": 0.08}},
    "delta": {"pass_rate": "+0.50"}
  }
}

来源:skills/skill-creator/references/schemas.md「benchmark.json」(约 219-305 行)。schema 末尾红字强调:configuration 必须正好是 "with_skill"/"without_skill"、pass_rate 必须嵌在 result 里——用 config 或把字段提到顶层都会让 viewer 显示空值(schemas.md:305)。

6. description 触发率优化:第二个循环

写完 skill 后还有一个独立的优化循环,专门优化「触发准不准」。它的精华是用数据驱动地改一句 description。

6.1 造 20 条触发评测 query(含正反例)

造 ~20 条 query,8-10 条 should-trigger、8-10 条 should-not-trigger:

[
  {"query": "…真实、具体、带细节的用户原话…", "should_trigger": true},
  {"query": "…近似但其实该用别的工具…",        "should_trigger": false}
]

关键在于 query 要真实、具体(带文件路径、列名、公司名、口语/typo),而且最有价值的反例是『近似命中』——共享关键词但其实需要别的东西。别造一眼无关的反例(给 PDF skill 配「写个 fibonacci 函数」太easy,什么都测不出来)。来源:skills/skill-creator/SKILL.md:338-358。

6.2 train/held-out 切分 + 选 test 最优

后台跑 scripts.run_loop,它会(skills/skill-creator/SKILL.md:376-394):

• 把评测集切成 60% train / 40% held-out test;
• 每条 query 跑 3 次取可靠的触发率;
• 让 Claude 根据失败项提改进版 description,在 train 和 test 上都重测,最多迭代 5 轮;
• 按 test 分数(而非 train 分数)选 best_description,以避免过拟合。

这套「切分 + 多次 + 按 held-out 选优」是从机器学习借来的防过拟合标准做法,被原样搬到了「调一句提示词」上——是本仓库很值得带走的一招。

注意:run_loop 要用当前会话所用的 model id(--model),让触发测试与用户真实体验一致(skills/skill-creator/SKILL.md:390)。脚本本体见 scripts/run_loop.py(本文未逐行读其内部,以 SKILL.md 描述为准)。

7. 边界与局限

• 多处依赖 subagent / 浏览器 / claude CLI。 Claude.ai 无 subagent → 跳过定量 benchmark、改串行自测;Cowork 无显示器 → viewer 用 --static 出静态 HTML;description 优化依赖 claude -p,只在 Claude Code/Cowork 可用。来源:skills/skill-creator/SKILL.md:420-455。
• run_loop.py/improve_description.py/generate_report.py 等脚本内部本文未逐行核读,引用的是 SKILL.md 对它们的描述与命令行用法,非脚本源码逐行。
• 简单 query 测不出触发质量(见 §6.1 与 index §3)。

8. 代码地图

主题	文件路径	符号 / 锚点
核心循环总览	skills/skill-creator/SKILL.md	顶部 + 「Repeating … the core loop」
推式 description	skills/skill-creator/SKILL.md	「Write the SKILL.md → description」
对照实验纪律	skills/skill-creator/SKILL.md	「Step 1: Spawn all runs」
评分/聚合/分析/viewer	skills/skill-creator/SKILL.md	「Step 4: Grade, aggregate…」
评测数据结构	skills/skill-creator/references/schemas.md	「grading.json」「benchmark.json」
触发优化循环	skills/skill-creator/SKILL.md	「Description Optimization」
聚合脚本	skills/skill-creator/scripts/aggregate_benchmark.py	—(命令行 aggregate_benchmark)
触发优化循环脚本	skills/skill-creator/scripts/run_loop.py	—(命令行 run_loop)
grader/analyzer/comparator	skills/skill-creator/agents/	grader.md,analyzer.md,comparator.md