Agent Skills 测试、评测与迭代
本节目标
把“看起来能用”变成格式、触发、执行和产物四层证据，并据此迭代。
四层验证
- 格式：
SKILL.mdfrontmatter 可解析，name、description 和目录符合规范。官方规范提供skills-ref validate ./my-skill。 - 触发：真实 should-trigger 与近似 should-not-trigger 查询是否按预期加载 Skill。
- 执行：步骤、脚本和错误恢复是否在干净上下文中可重复。
- 产物：输出是否满足可观察断言，并且相对无 Skill/旧版基线确有改进。
只做格式验证不能证明任务质量；只看一次漂亮输出又可能掩盖误触发、边界失败和基线本来就会做的问题。
设计 eval case
官方指南把一个 case 拆为：真实 prompt、期望输出和可选输入文件。可以先用 2～3 个执行用例暴露输出形状，再扩展具体 assertions；触发边界则需要更平衡的正反样本。本课程 evals.json 加入了 should_trigger 与 reason 作为本地教学字段，不应误称为所有 client 通用的 eval schema。
好断言：
- “stdout 是合法 JSON”；
- “JSON 同时包含
words、characters、lines”； - “无
--text时退出码非零且错误指出缺少参数”。
坏断言：“输出很好”不可验证；“必须逐字等于某句说明”又可能过脆。
有 Skill 与基线
每个 case 在干净上下文运行两次：一次加载 Skill，一次不加载（或使用旧版本）。保持 prompt、输入和运行环境相同，记录：
- 每条断言 PASS/FAIL 及具体证据；
- 时间和 token 成本（如果 client 能可靠提供）；
- 错误恢复、额外工具调用和人工干预；
- 人工对可用性、安全和表达质量的复核。
机械检查优先用脚本；风格与“是否真正有帮助”等难量化属性保留人工评审。若两组都通过，断言可能太容易或 Skill 没有增益；若两组都失败，先检查 case 和断言是否合理。
迭代顺序
- 从执行轨迹找具体失败，不凭感觉扩写整篇 Skill；先判断 agent 是否发现了正确 Skill、读了哪些资源、运行了什么命令。
- 判断问题属于触发、指令、资源、脚本还是测试本身。
- 做最小修改，保留旧版作为基线。
- 重跑原用例与未参与修改的新验证用例。
- 记录收益和成本；没有稳定增益的内容应删减。
本地验证器的定位
本知识库的 examples/validate_skill.py 只用标准库检查教学样例的核心约束和文件引用。它不完整解析 YAML，也不替代官方 skills-ref。项目验收时会实际运行本地验证器；若环境未安装 skills-ref，应明确记为未验证项而不是声称官方校验通过。
练习与自测
- 给你自己的 Skill 写一个正常、一个边界、一个近似负例。
- 为每个输出写至少一条机械断言和一条人工复核问题。
- 自测：为什么应在第一次运行后再完善断言？真实输出会暴露哪些质量维度可观察，也能避免凭空写错检查。
下一步
完成 项目：创建并验证技能。
参考资料
- Evaluating skill output quality（获取日期：2026-07-14）
- Optimizing skill descriptions（获取日期：2026-07-14）
- Agent Skills Specification: Validation（获取日期：2026-07-14）