evaluate-skill

评估技能

使用 Caliper：运行技能评估，阅读结果，并追踪每项失败对应的修复位置。

前提条件

caliper CLI 必须位于 PATH 中。此技能可以在没有 Caliper 仓库的情况下复制到 Agent 中，因此如果缺少它，请先安装：

pipx install caliper-eval

caliper <command> --help 是命令行标志的权威说明。REFERENCE.md 涵盖完整的规范格式、引擎以及结果的含义。

四个问题

技能评估回答四个彼此独立的问题。每个问题都有自己的衡量方式和修复位置，因此请将它们分开：混合后的数字会掩盖究竟哪一部分出了问题。

问题	衡量方式	失败时的修复位置
触发：Agent 会在应该使用技能时调用它，并且只在那时调用吗？	任务中的 activates: 和触发探测	技能的 description frontmatter
有效：触发后，它能完成任务吗？	expect: / assert:，以成功率计分	技能正文
有价值：它的表现是否优于不使用它的 Agent？	对照组（--ablate <skill-name>：声明的邻域中除该技能之外的部分）和 caliper compare。若要使用真正精简的 Agent，则消融所有已声明的技能和所有已声明的 mcp: 服务，并隔离运行	任务：如果对照组也能通过，说明任务太简单
稳定：经过编辑和一段时间后，它仍能保持良好表现吗？	使用 caliper compare 将每次完整运行与上一次进行比较，以衡量技能偏移	导致变化的编辑

规范结构

skills:
  - ./SKILL.md              # relative to the spec; installed, never preloaded
tasks:
  - name: What success looks like
    prompt: <what a real user would type; never names the skill>
    expect: <natural-language pass/fail criterion>
    assert: |               # optional deterministic Python check
      assert ...
    activates: [my-skill]   # frontmatter name: of the skill that should fire
  - name: Unrelated work stays unrelated
    prompt: <work no declared skill should answer>
    activates: []           # a trigger probe: no judge, cheap

编写规范时，每个带有 expect: 或 assert: 的任务也会检查 activates:，包括拒绝执行的情况：技能，以及该任务上它委派给的任何已声明技能；每条提示词都应像真实用户的请求，并且不提及技能名称。

规范中没有 backend/model 或 judge: 块。运行时会独立选择技能和评审使用的引擎：caliper run <spec> --model codex 会使用 codex 运行并评分，而 --judge-model 可指定不同的评审模型。后端包括 claude-code（默认）、codex、pi 和 hermes。每次尝试都会在全新、空白的工作目录中运行，因此 setup: 应使用相对路径在该目录中构建测试夹具。

运行

1. caliper validate <spec>。它绝不会访问网络。
2. 运行 caliper run <spec> --k 1，以排查规范和测试框架错误。先修复这些问题，再查看任何分数。
3. 运行一次 caliper run <spec> --k 3 --ablate <skill-name>（如果某个 mcp: 服务与技能同名，则填写 skill:<skill-name>）。这是对照组：不含该技能的已声明邻域。技能未安装，因此编辑 SKILL.md 不会影响其分数。保留其结果路径（caliper list <spec-name> 会标记消融运行），并重新与之比较。只有在任务或已声明技能发生变化时才重新运行。
4. 运行 caliper run <spec> --k 3，然后运行 caliper compare <control.json> <spec-name>，查看该技能是否物有所值。每次编辑后，也要与上一次完整运行的路径比较，确认编辑是否保持了效果：技能即使表现变差，也仍可能优于对照组。仅指定规范名称时，会解析为该规范的最新运行。

如果运行因 Not logged in 而停止，询问用户是否要运行错误信息中提到的登录命令。取得用户同意后再运行（它会打开浏览器供用户完成登录），然后重新运行；未经同意绝不运行。hermes model 是交互式选择器，因此请用户在自己的终端中运行它。

读取结果

成功率（successes / usable）是核心指标。pass@k 和 pass^k 是 --verbose 下的次要视角。激活情况是单独的计分板，统计的是不同的样本群体：应将其与成功率并列报告，绝不要把它们平均在一起。

追踪每项失败任务，找出应该在哪里修复：

信号	修复位置
运行以 2 退出（后端配置错误、模型不可用、钩子或 MCP 服务失败，或所有尝试都不可用）	环境或任务的钩子。应报告为配置问题，而不是任务失败
⊘ 不可用的尝试（infra_error、timeout、judge_error）	不是技能的问题：速率限制、身份验证或评判器导致。它们不计入得分；请重新运行
cheat 结果	任务：它泄露了答案。收紧任务要求或 sandbox:
激活失败：预期的技能未触发	该技能的 description
激活失败：意料之外的技能也触发了	多出的技能的 description，或两者之间的重叠
激活失败，因为用户自己的技能触发了（报告标头中的 skill:）	不只是 description 的问题：在用户的配置中，该技能确实构成竞争。与用户决定是改进描述，还是隔离运行
激活通过，但得分低	技能正文
评判器的推理表明 expect: 有歧义	任务评分方式：让判定标准可观察，或添加 assert:
完整运行 ≈ 对照组，且技能在完整运行中触发了	任务：它并不需要该技能。如果技能从未触发，则应修复其 description（见上文）

当 k=3 时，一次尝试就会造成 33 分的波动。判定更改是改进还是回退之前，请在 k≥5 时重新运行。caliper compare 会标记任何下降，但不会阻止发布。改写或缩短后的技能在 k≥5 时得分保持在此前得分约 5% 以内且仍高于对照组，就可以安全发布。

测量的是谁的配置

默认情况下，运行会加载用户自己的自定义项（用户技能、插件、规则、设置和连接器；后端例外情况见 REFERENCE.md），以回答“我的技能在我的 Agent 中是否有效？”。比较后端或模型、将结果用于本机以外的场景（共享、发布或与他人的运行结果比较），或测量纯 Agent 时，应使用 隔离模式（--no-user-customizations，或在规范中设置 user_customizations: false）。每种配置都不同，否则差异的一部分就来自各自的配置。对用户自己的技能使用 --ablate 无需隔离，因为两次运行加载的是相同配置。

务必告知用户运行采用了哪种模式以及加载了什么：查看报告标头中的 user customizations: 行（若不存在，则表示已隔离），并转达 caliper compare 就此提出的任何修复建议。

还没有评测？

如果用户尚未决定要测试什么（技能没有 .eval.yaml，或希望找出评测中的不足），建议使用 grill-skill：它会采访用户并编写规范。若要自行设计任务，请参阅 REFERENCE.md 中的“设计评测”。

完成条件

• 每项任务都有可观察的判定标准，且至少有一项包含确定性的 assert:；
• 执行任务声明了 activates:，且规范至少包含一个触发探测任务；
• 完整运行在执行任务上优于对照组，并且不低于此前的完整运行。触发探测任务没有执行得分：请从完整运行的激活情况中读取结果；
• 规范通过 caliper validate；
• 已告知用户将 .eval.yaml 与 SKILL.md 放在一起提交。保存在 .caliper/results/ 下的运行结果便于长期对比，可安全地加入 gitignore。