skill-evaluator

Skill Evaluator

测试一项技能是否正确、易发现且有价值，而不只是看它的单元测试是否通过。该测试框架与 Agent 无关：它会驱动用户使用的任何编码 Agent CLI，因为 Agent Skills 可在所有这些工具间通用。

各层何时使用

共分为三层，成本和保真度依次递增（完整说明见 references/methodology.md）：

层	问题	脚本	需要 CLI 吗？
1. 确定性	脚本是否输出了文档中说明的数值？	run_script_checks.py	否
2. 触发	描述是否会在正确的提示词下触发？	run_trigger_eval.py	是
3. 质量	遵循 SKILL.md 是否优于不使用技能？	run_quality_eval.py → 评分 → aggregate_benchmark.py	是

始终运行第 1 层（免费）。如果可以运行编码 Agent CLI，再增加第 2～3 层。

步骤 0 — 选择 Agent CLI

询问用户使用哪种编码 Agent，然后将其映射到适配器 ID。支持： claude-code、openai-codex、antigravity（于 2026-06-18 取代 Gemini CLI 的 agy CLI）、cursor-cli、github-copilot-cli、amp、opencode、 grok-cli。完整列表和身份验证信息见 references/adapters.md，或运行：

python scripts/agent_adapters.py list

确认已安装对应的二进制文件，并设置了身份验证环境变量（适配器列表中有说明）。 在进行任何实际运行之前，先执行试运行，查看确切命令：

python scripts/agent_adapters.py build <agent> --prompt "test" --workdir /tmp/wd

步骤 1 — 确定性脚本检查（始终执行）

python scripts/run_script_checks.py --skill <path-to-skill> --json

读取技能 evals/evals.json 中的 script_checks，执行每个脚本，并根据可由机器检查的断言对其 --json 输出进行评分。任何一项失败时都会返回非零退出码，可安全用于 CI。如果技能的 script_checks 很少或没有，请为每项答案可计算的评估添加检查（架构见 references/schemas.md）；这是防止文档与代码不一致的成本最低、最持久的保障。

步骤 2 — 触发／发现评估

描述是否会在正确的提示词下触发，并对近似但不匹配的提示词保持沉默？

# Dry-run first (prints the per-CLI commands, runs nothing):
python scripts/run_trigger_eval.py --skill <path> --agent <agent> --dry-run

# Real run with a labelled query set (~20: half should-trigger, half near-miss):
python scripts/run_trigger_eval.py --skill <path> --agent <agent> \
  --queries queries.json --runs-per-query 3 --json

根据 references/methodology.md 设计查询集（包含正向查询和有迷惑性的负向查询）。如果不使用 --queries，技能的评估提示词会作为应触发案例；要进行真正的区分测试，请添加负向查询。

步骤 3 — 输出质量评估（使用与不使用技能的差异）

核心指标：遵循 SKILL.md 的 Agent 是否优于不使用技能？

# 1. Dry-run the plan (no tokens spent):
python scripts/run_quality_eval.py --skill <path> --agent <agent> \
  --workspace <skill>-workspace --dry-run

# 2. Real run: with-skill AND no-skill baseline, isolated clean dirs each:
python scripts/run_quality_eval.py --skill <path> --agent <agent> \
  --workspace <skill>-workspace --iteration 1 --json

此步骤会将技能安装到临时项目的技能目录中，用于使用技能的运行；同时运行不使用该技能的干净基线，并为每次运行保存 outputs/、response.txt 和 timing.json。

然后为每次运行评分：依据其 assertions 进行评分，并编写 grading.json （见 references/grader.md——重新推导数值、要求提供具体证据、不设部分分，并审查薄弱断言）。对于可通过机械方式检查的断言，复用第 1 层，而不是凭目测判断。

然后汇总到基准测试中，计算差值：

python scripts/aggregate_benchmark.py <skill>-workspace/iteration-1 \
  --skill-name <name> --agent <agent> --json

run_summary.delta.pass_rate 就是该技能的价值。揭示平均值掩盖的问题模式（见 references/methodology.md）：无法区分结果的断言、高方差评估，以及时间／Token 权衡。

然后生成评审报告，并在自我评分之前将其展示给用户（独立 HTML 页面，无需服务器）：

python eval-viewer/generate_review.py <skill>-workspace/iteration-1/benchmark.json -o review.html

报告会呈现使用与不使用技能的差值、各配置的统计数据，以及可展开的逐项评估明细，列出每条评分断言的文本、通过／失败状态和证据。

步骤 4 — 迭代

根据各种信号改进技能（失败的断言、对薄弱断言的反馈、执行记录、人工评审），注重泛化而非过拟合，保持精简，解释原因，并将重复工作整合到脚本中。重新运行并输出到 iteration-<N+1>/，然后进行比较。当结果令用户满意、反馈为空或收益趋于平稳时停止。若要判断“新版本是否真的更好？”，请使用 references/methodology.md 中介绍的盲测比较方法。

要报告的输出

• 第 1 层：通过的检查项／断言；发现的文档↔代码不一致之处。
• 第 2 层：触发通过率（成功触发的正例、保持静默的负例）。
• 第 3 层：启用技能与未启用技能的通过率差值，以及时间／令牌开销。

参考文件

• references/adapters.md — 各 CLI 的无头模式命令、技能目录、身份验证和注意事项。
• references/methodology.md — 严谨的实践方法（进行非简单评估时请阅读）。
• references/grader.md — 如何将运行结果评定并写入 grading.json。
• references/schemas.md — 每个文件的精确 JSON 结构。
• eval-viewer/generate_review.py — 将基准测试渲染为独立的 HTML 评审页面。

验证清单

在满足适用于所运行层级的每一项之前，不要报告结论：

• 第 1 层：运行了 run_script_checks.py --json，记录了 summary 行（checks_passed/checks、assertions_passed/assertions），并确认 ok: true（进程退出码为 0）——非零退出码表示文档↔代码不一致，不能算作技能通过。
• 第 1 层：至少手动重新推导了一项数值断言的预期值，并确认脚本输出的值与之匹配（例如，在指定的 rel_tol／abs_tol 范围内的 approx）——不能只看断言的 passed 标志是否为 true。
• 第 1 层：记录了 cases_without_checks；如果有可计算的评估缺少 script_check，应将其注明为覆盖缺口，而不能把本次运行视为已全面验证。
• 第 2 层：使用包含正例和易混淆负例的标注集运行了 run_trigger_eval.py，并记录各类别的通过数量（以不低于阈值的速率触发的正例、保持在阈值以下的负例）——仅运行正例测量的是召回率，而非区分能力。
• 第 2 层：设置了 --runs-per-query ≥ 3，并记录每个查询的 trigger_rate；将触发率接近 --threshold 的查询标记为不稳定，而不是计作明确的通过／未通过。
• 第 3 层：运行了启用技能（with_skill）和未启用技能（without_skill）基线，并报告 run_summary.delta.pass_rate（核心指标）的均值 ± 标准差——绝不能只报告启用技能时的绝对通过率。
• 第 3 层：根据每次运行 outputs/ 中的实际文件进行评分（按照 references/grader.md 重新推导数值／打开产物），为每项预期记录具体的 evidence，并在下结论前向用户展示输出或 benchmark.md。

常见陷阱与自我辩解

诱人的捷径	为什么不对／应该怎么做
“脚本运行完毕并以 0 退出，所以这个技能没问题。”	退出码为 0 只表示进程没有崩溃；只有断言或 expect_exit 失败时，run_script_checks.py 才会返回非零值。请查看 assertions_passed/assertions 的计数，并至少重新推导一个数字——脚本可以正常运行，却仍然输出错误的值。
“断言通过了，所以数字没错。”	即使运行结果错误，较弱的断言（例如“提到了 cfl_checker.py”，或对某个字段使用 exists/truthy）也会通过。请使用值与结论断言（使用 approx/eq 和重新推导出的预期值），并根据评分器中指出断言过于容易满足的 eval_feedback 采取行动。
“我的所有触发查询都触发了，所以发现机制有效。”	只有正例的集合衡量的是召回率，而不是精确率；一个过于宽泛、什么都触发的描述也能通过。你需要加入难以区分的近似反例，并确保它们低于 --threshold——没有这些反例，区分能力测试就毫无意义。
“每个查询运行一次，就足以了解触发率。”	检测是基于对话记录的启发式判断，触发具有随机性；单次运行只能得到 0 或 1 的比率。请使用 --runs-per-query ≥ 3，并将徘徊在阈值附近的比率视为不稳定，而非定论。
“使用技能时的通过率很高，所以这个技能很有价值。”	价值看的是使用／不使用技能的差值，而不是绝对通过率。如果 Agent 不用技能也能出色完成任务，差值就约为 0，而技能可能只会增加延迟和令牌消耗。务必运行 without_skill 基线，并报告 delta.pass_rate。
“断言都通过了，没必要打开输出文件。”	自动评分只会检查你决定断言的内容，而且对话记录可能声称做了实际上并未完成的工作。请打开 outputs/ 中的文件，重新推导数字，阅读 user_notes.md，并在宣布技能合格前审阅 benchmark.md（或请用户审阅）。

安全

输入验证

• --agent 会根据已知适配器 ID／别名的固定允许列表进行解析 （agent_adapters.py）；未知值会被拒绝（退出码为 2）。
• --skill 必须是包含 SKILL.md 的目录，否则运行器会以退出码 2 退出。
• script_checks 运算符和点分路径会与固定集合进行匹配；不会对用户字符串调用 eval()，也不会将其传递给 shell。

文件访问

• 确定性层会使用真实解释器运行技能自带的脚本，并且只读取该技能的 evals/evals.json。
• 质量层和触发层会在用户指定的工作区下创建隔离的工作目录，将技能复制到其中，并在其中写入结果。

工具限制

• Bash：运行测试框架的 Python 脚本和选定的编码 Agent CLI。
• Read/Grep/Glob：检查技能和结果。Write：搭建工作区。

安全措施

• 不使用 eval()/exec()；子进程调用使用明确的参数列表（绝不使用 shell=True）；命令根据适配器规范构建，而非通过字符串拼接。
• 触发层／质量层会传递各 CLI 的自动批准标志（例如 --dangerously-skip-permissions），这会降低 Agent 运行时的安全防护。 只评估你信任的技能，最好在沙箱／容器中进行。务必先使用 --dry-run 检查确切命令。身份验证信息从环境变量读取，绝不会作为命令参数传递。

局限性

• 第 2–3 层需要安装并完成身份验证的受支持 CLI；否则只能使用第 1 层。
• 触发检测是一种跨工具启发式判断（对话记录是否调用了技能）；若要在 Claude Code 上实现最精确的检测，请解析其 stream-json 工具使用事件。
• 令牌统计尽力而为——只有部分 CLI 会在无头输出中报告使用情况。
• 新 CLI（Antigravity、Grok）的置信度为中等；请通过供应商提供的 --help 和 --dry-run 核验标志。