给 Skill 写 Eval

它替你干掉什么：干掉「我觉得这版更好」

第一条立刻能跑的用法

# 路径 A：内置 runner。先长出一个用例骨架（在 plugin / skills 目录根下跑）
claude plugin eval init --bare my-first-case
# → 生成 evals/my-first-case/prompt.md 和 evals/my-first-case/graders/criteria.md

# 填完之后，对当前目录跑三遍，并写一份自包含 HTML 报告
claude plugin eval . --runs 3 --report ./eval-report.html

# 路径 B：装官方 skill-creator，让它替你把整套流程跑完
/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official
/reload-plugins
# 然后直接说：evaluate my summarize-changes skill with skill-creator

# 路径 C：兜底。在 .claude/settings.local.json 里把 skill 关掉，开新会话再跑一遍
{ "skillOverrides": { "summarize-changes": "off" } }

# 跑之前先做一次五秒体检：frontmatter 有没有静默解析失败
claude plugin validate .claude/skills

init --bare 吐出来的模板小得让人意外——prompt.md 的头部只有 max_turns 和 allowed_tools，graders/criteria.md 的头部只有 type 和 weight，正文各一句 TODO。用例就是目录，不是配置文件：一个用例一个文件夹，里面一份 prompt 加一个 graders/。

机制：它凭什么能把「感觉」变成数字

① 对照臂：默认就跑，不是可选项

claude plugin eval 的 --ablation 默认值是 with-without——只要目标解析出一个 plugin，它就自动加跑一条「没有这个 plugin」的臂，然后报告分数差。为什么必须默认打开？因为模型本来就很强。你的 skill 说「写 commit message 要用 conventional commits」，模型不带 skill 也可能这么写——不跑对照臂，这一分你会算到自己头上。skill-creator 那边把同一件事说得更死：with-skill 和 baseline 两组必须「在同一个 turn 里 spawn」，不许先跑完带 skill 的、过两天再补基线。

② 触发 ≠ 质量：with-only 打分器不计入分数

这是最见功力的一处。在 with-without 模式下，标了 with-only 的打分器（包括 tool_used: Skill）被当成「plugin 有没有被点着」的指示器，而不是分数的一部分。理由很直白：没装 skill 的那条臂当然不可能触发 skill，把这条算进分差等于白送自己一分。触发率和输出质量必须分开量——skill-creator 为此专门有一个 description tuning 步骤，生成 should-trigger 和 should-not-trigger 两组 prompt，量命中率，然后反过来改 description。

③ 打分器分两类：先榨干免费的

把一个非法的 type 塞进 grader，CLI 会把合法值全吐出来：regex | tool_order | tool_used | file_exists | llm | baseline。前四个是纯程序判定，不花钱也不引入方差；后两个是模型调用（--judge-model 默认 haiku）。这条分界线直接决定了你该怎么设计用例：能把成功标准写成「产出了 output.txt」「先 Read 后 Edit」「输出里出现了 feat(」的，就别写成一句让 LLM 去意会的「输出应当专业且清晰」。这也正是官方评估文档那条原则——宁可要更多题、判得糙一点，也不要更少题、人工精判。

④ 重复次数：默认就是 3

--runs 的默认值是 case.runs ?? 3。单次跑赢在 agent 评估里几乎没有信息量，因为同一个 prompt 两次跑出的轨迹可能完全不同。skill-creator 把这一步做到了报表里：python -m scripts.aggregate_benchmark 产出的 benchmark.json / benchmark.md，给每种配置写的是 pass_rate、时间、token 的 mean ± stddev 以及 delta。看到 delta 先看 stddev——差值淹在标准差里的，那不叫提升。

真实用法与边界：五步、三题、两个 Claude

五步（出处：Skill authoring best practices · Evaluation and iteration）

1. 找缺口：不带 skill 跑真实任务，记下具体是哪里失败、缺哪块上下文。
2. 造题：就着这些缺口建三个场景。skill-creator 的说法是「2–3 个真实用户会说的 prompt」，并且明确要求先只写 prompt、断言留到跑的时候再补——因为你还不知道它会怎么错。
3. 量基线：测没有 skill 时的表现。
4. 只写刚好够的字：够补缺口、够通过评估就停。
5. 迭代：跑评估，对照基线，改。

Claude A / Claude B：为什么必须是新会话

官方推荐开两个实例：Claude A 帮你写和改 skill，Claude B 装着它去干真活，你把 B 的翻车现场带回给 A。文档举的例子很具体——「我让 B 出区域销售报表，它写了查询但忘了过滤测试账号，skill 里明明提了这条规则」，A 的回应可能是把 always 改成 MUST，或者调整章节顺序。

「fresh session」这四个字是硬要求，不是修辞：官方明说，写 skill 时留在会话里的上下文会掩盖 SKILL.md 本身的缺口——你以为它读懂了，其实它是记得你刚才口头说过。claude plugin eval 和 skill-creator 都用子代理跑用例，正是为了每条用例都拿到干净上下文。

三个工具各自量的是什么，别搞混

• claude plugin validate（v2.1.233+）——只查 frontmatter YAML 能不能解析。它抓的是一种极隐蔽的故障：YAML 挂了，skill 正文照样加载，但 metadata 是空的，于是 /skill-name 手动调还能用，自动触发永远不会发生。跑 eval 之前先跑它，五秒。
• /skill-doctor（v2.1.252+）——量的是使用度和 context 开销，不是质量。它列出每个 skill 花了多少 context、被调用过几次，并标出从来没被触发过的。交互式会话里结果开在 /plugin 的 Stats 页，-p 非交互模式下直接打文本。注意它跑不了的地方：Remote Control 连接下会直接回「Skill usage reports are not available on this connection.」，得回到会话真正运行的那台机器的终端上跑。
• skillOverrides——四档可见性（on / name-only / user-invocable-only / off），写在 .claude/settings.local.json，/skills 菜单里按空格循环、Esc 保存。当成穷人版消融开关用。边界：它对 plugin skill 无效，那些得走 /plugin。

代价与替代品：eval 比 skill 贵，而且会腐坏

诚实的代价

• 账单是乘出来的。每条用例 = runs × 两条臂 × 每次一个完整 agent run，默认就是 3 × 2 = 6 次；llm 和 baseline 两种打分器还各是一次模型调用。claude plugin eval 给了 --max-cost-usd 做硬顶，撞顶时中止并返回部分结果（exit 2），超支被限制在一次 agent run 内，且那一次的付费打分器会被跳过、免费打分器照常打分。第一次跑一定要带上它。
• 紧和松都会骗你。断言写太紧 → 高方差、天天红；写太松 → 两臂同分、delta 恒零。这两种都表现为「eval 没用」，但病因相反，得靠 analyst pass 区分。
• early access 的东西不能进 CI。--threshold（默认 1.0，低于就 exit 1）和 --json 摆明是给流水线用的，但账号没开通时命令直接退出。要进 CI，先确认它在 CI 那个身份下真的能跑。
• 文档自己还没对齐。best practices 那页至今仍写着「there is not currently a built-in way to run these evaluations」，而 Claude Code 文档里已经有一整节 evaluate-and-iterate。两页官方文档打架时，以能跑的命令为准。
• eval 会腐坏。模型换代之后，原来区分得开的题可能新模型不带 skill 也能全过——你的 delta 会自己缩到 0。官方要求在 Haiku / Sonnet / Opus 上各测一遍，本质上就是在提前暴露这件事。
• 没有子代理就没有基线。skill-creator 自己写明：在拿不到子代理的环境里，跳过定量 benchmark，因为基线对比在那种情况下不成立，只能退回人工定性反馈。别在那种环境里假装自己在做评估。

不装它你还能怎么办

• promptfoo —— 通用的 prompt / agent / RAG 评估器，据 GitHub 仓库页 2026-09 约 2.49 万 star。装法 npm install -g promptfoo，起手 promptfoo init --example getting-started；支持 LLM-as-judge 断言，官方主打 CI 集成。什么时候别用：它不懂 Claude Code 的 skill 触发机制——它能评「这段 prompt 的输出好不好」，评不了「这个 skill 该不该被点着」。
• Inspect AI —— 英国 AI Security Institute（AISI）的评估框架，据 GitHub 仓库页 2026-09 约 2.7 千 star；据 PyPI，最新版 0.3.263 发布于 2026-09-04。装法 pip install inspect-ai，自带 model-graded scorer 和两百多个预置评估。什么时候别用：它是研究级基建，为的是横评模型能力；拿它评一份 SKILL.md 是高射炮打蚊子。
• 手动双跑 —— 官方文档自己列出的兜底：几条真实 prompt，各开一个新会话，一次带 skill 一次用 skillOverrides 关掉，肉眼比。什么时候够用：skill 只有你一个人用、改动是纯文案、或者你只是想确认它到底触没触发。