grill-skill

Grill Skill

采访用户以设计技能的评测，然后反复执行 → 诊断 → 改进，直到发布。需要 caliper（如果尚未安装，请运行 pipx install caliper-eval）。命令、规范骨架和任务编写规则见：REFERENCE.md。

评测要回答四个问题，采访会逐一涵盖：

• 触发：Agent 是否会在应该使用技能时调用它，而且只在该使用时调用？通过 activates: 和触发探测进行测试。通过修改 description 修复。
• 奏效：触发后，它能否完成任务？通过 expect: / assert: 进行测试。通过修改正文修复。
• 胜出：它是否胜过不使用该技能的 Agent？通过与对照组比较来测试：也就是移除该技能后，已声明的邻近技能集合。如果对照组也能通过某项任务，就修改该任务。
• 保持：经过编辑后，效果是否依然良好？通过将每次新的完整运行与上一次运行比较来测试。

入口

/grill-skill [path]：可选的 SKILL.md 路径。

• 提供了路径：使用该路径。
• 未提供路径：在当前工作目录中查找 SKILL.md；如果找到，先确认再继续，否则询问其位置。

阶段 1 — 了解

阅读 SKILL.md。总结它的用途、触发时机，以及成功运行的表现。请用户确认你的理解。收到确认前不要继续。

阶段 2 — 确定评测模式

在 SKILL.md 同级目录中查找 *.eval.yaml（优先尝试 <dir-name>.eval.yaml）。

• 未找到 → 新建评测。找到 → 补全缺项。

一次只问一个问题，并等待每个问题的回答。根据用户的回答构建每项任务，并在采访结束后才编写规范。

新建评测

一次只问一个问题，依次了解：

1. 顺利路径：最常见的成功用法是什么？Agent 做了什么？什么能证明任务成功？
2. 边缘情况：有什么棘手但有效的输入可能会让基础 Agent 出错？
3. 对抗情况：技能应该拒绝或避免什么？
4. 邻近技能：Agent 可能会把哪些其他技能与此技能混淆？对于用户能指出的每项技能（路径或 git 仓库），将其声明在 skills: 中，并添加一个邻近技能探测：属于该邻近技能的提示词，并设置 activates: [<neighbour>]。

始终提议添加一个静默探测：无关任务，activates: []。

将每个回答转换为一项任务：编写一个切实可行的 prompt，其中绝不提及技能名称；设置可观察的 expect，并在结果可检查时设置 assert；对于执行任务，设置 activates:，列出该技能以及该任务委托给的任何已声明技能，以便运行时区分 description 失效和正文失效。测试框架只运行一次：没有人会回答 Agent 的问题。如果技能会先提问再行动，则任务评估其第一轮响应：在 expect: 中写出问题，并在 assert: 中断言尚未执行任何操作。展示拟定的 YAML 并请求确认，然后再写入文件。

在 SKILL.md 同级目录中编写规范，命名为 <dir-name>.eval.yaml，其中包含 skills: [./SKILL.md]，且不包含 engine：后端和模型会在运行时通过 --model / --judge-model 选择，因此，如果 SKILL.md 面向非默认 Agent，请告知用户应传入哪个标志。然后告知用户现在将规范与 SKILL.md 一起提交。

补全缺项

阅读现有规范，并按所回答的问题对任务进行分组并汇报。指出缺少任务的问题：没有 activates: 的执行任务、没有触发探测、没有确定性的 assert:。在提出或编写任何内容之前，先询问还缺少哪些行为或哪些行为测试不足，即使用户只是让你检查规范也不例外。将每个缺项细化为一项任务，展示后征求确认，再将其写入文件。

测量的是谁的配置

默认情况下，运行会加载用户自己的自定义项（用户技能、插件、规则、设置和连接器；后端例外情况见 REFERENCE.md），这回答的是“我的技能在我的 Agent 中是否有效？”。比较后端或模型、结果要离开这台机器（共享、发布或与他人的运行结果比较），或测量纯 Agent 时，请隔离（使用 --no-user-customizations，或在规格中设为 user_customizations: false）；每套配置都不一样，否则差异中也会包含配置造成的影响。对用户自己的技能使用 --ablate 无需隔离，因为两次运行加载的是同一套配置。

始终告知用户运行采用了哪种模式以及加载了哪些内容，依据报告标题中的 user customizations: 行（若没有该行，则表示已隔离），并转达 caliper compare 针对配置提出的任何修正建议。

阶段 3 — 首次运行

先验证规格，再以 k=1 运行（命令见 REFERENCE.md）。展示结果。继续之前，先修复任何测试框架或配置错误（而非任务失败）。如果运行因 Not logged in 停止，询问用户是否要运行错误提示中列出的登录命令。获得用户同意后再运行（这会打开浏览器供用户完成操作），然后重新运行；未经同意绝不运行。hermes model 是交互式选择器，因此请用户在自己的终端中运行。

阶段 4 — 检查任务是否需要该技能

在任何人编辑技能之前，先检查这些任务能否将其与对照组区分开来：即移除该技能后的声明邻域。运行对照组（使用 --ablate <skill-name>；若同名 mcp: 服务共享该名称，则使用 skill:<skill-name>）和完整运行，两者都设为 k=3，然后用 caliper compare 比较。先检查激活情况：如果完整运行中技能从未触发，那么两次运行测量的是同一个 Agent，应该修复的是其 description（阶段 5），而不是任务。

• 技能已触发，且对照组的得分与完整运行差不多：任务不需要该技能，因此针对这些任务迭代技能毫无意义。与用户一起完善任务（使用更难的输入，或加入技能带来的具体规则），然后重新运行两者。
• 完整运行明显领先：任务确实测量了该技能。保留任务。

保留对照组的结果路径（caliper list <spec-name> 会显示哪个运行进行了消融）。该运行中未安装此技能，因此编辑 SKILL.md 不会改变其数值：应与其重新比较差异，而不是重新运行。只有在任务或声明的技能发生变化时，才重新运行它。

阶段 5 — 诊断并迭代

建议修复方案前，先阅读每个失败的任务，并说明修复应放在哪里：

信号	修复位置
运行以 2 退出（后端配置错误、模型不可用、钩子或 MCP 服务失败，或所有尝试均不可用）	环境或任务的钩子，而不是技能。修复后重新运行
⊘ 不可用的尝试（infra_error、timeout、judge_error）	不是技能的问题：速率限制、身份验证或评判器。修复后重新运行
cheat 结果	任务：它泄露了答案。收紧任务或 sandbox:
激活失败：预期的技能未触发	该技能的 description
激活失败：意外的技能也触发了	多出的技能的 description，或两个技能之间的重叠
激活失败，因为用户自己的技能触发了（报告标题中的 skill:）	不只是 description 的问题：该技能在用户的设置中确实构成竞争。与用户商定是调整描述，还是隔离本次运行
激活通过，但分数低	技能正文
评判器的推理表明 expect: 含糊不清	任务评分：让判定标准可观察，或添加 assert:
完整运行 ≈ 对照运行，且技能在完整运行中触发	任务（参见阶段 4）。如果它从未触发，则检查 description

然后询问用户是要继续迭代还是结束。

• 迭代：用户编辑 SKILL.md 后，以 k=3 重新运行，并用 caliper compare 与之前的完整运行比较两次：一次检查修改是否有效，另一次检查它是否仍比保留的对照运行更有价值。技能即使表现变差，也仍可能胜过对照运行。再次诊断。在 k=3 时，单次尝试会造成 33 分的波动，因此采取行动前，应在 k≥5 时确认意外的胜出或失利。循环进行。
• 完成：确认完整运行在执行任务上胜过对照运行，且表现不逊于之前的完整运行，然后提醒用户将 SKILL.md 和 .eval.yaml 一起提交。