Agent Skills

评估 Skill 输出质量

通过评测驱动的迭代,检验 Skill 能否产出高质量结果。

你编写了一个 Skill,用一条 Prompt 试过,看起来有效。但换一种请求、遇到边界情况时,它还能稳定工作吗?它的效果真的优于完全不用 Skill 吗?结构化评测能回答这些问题,并为系统改进 Skill 建立反馈循环。

设计测试用例

一个测试用例包含三部分:

  • Prompt:贴近实际的用户消息,也就是人们真正会输入的请求。
  • 预期输出:用清楚易懂的文字描述什么样的结果才算成功。
  • 输入文件(可选):Skill 需要处理的文件。

将测试用例保存在 Skill 目录中的 evals/evals.json:

evals/evals.json

{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "我在 data/sales_2025.csv 中有一份月度销售数据。能找出营收最高的 3 个月,并制作一张柱状图吗?",
      "expected_output": "一张展示营收最高的 3 个月的柱状图图片,坐标轴和数值均有标注。",
      "files": ["evals/files/sales_2025.csv"]
    },
    {
      "id": 2,
      "prompt": "下载文件夹里有个 customers.csv,有些行没填邮箱,能帮我清理一下,再告诉我一共缺了多少吗?",
      "expected_output": "一份已处理缺失邮箱的清理后 CSV,以及缺失邮箱的数量。",
      "files": ["evals/files/customers.csv"]
    }
  ]
}

编写测试 Prompt 的建议:

  • 从 2–3 个测试用例开始。 在看到第一轮结果前,不必投入过多。之后可以逐步扩充。
  • 让 Prompt 有所变化。 使用不同的表达方式、详细程度和正式程度。有些请求可以随意一些(“能帮我清理一下这个 csv 吗”),有些则要精确(“解析 data/input.csv 中的 CSV,删除 B 列为空值的行,将结果写入 data/output.csv”)。
  • 覆盖边界情况。 至少包含一条用于检验边界条件的 Prompt,例如格式错误的输入、不常见的请求,或 Skill 指令可能存在歧义的情况。
  • 使用真实的背景信息。 用户通常会提及文件路径、列名和个人背景。“处理这些数据”之类的 Prompt 过于模糊,无法开展有意义的测试。

暂时不必定义具体的通过或失败条件,只需准备 Prompt 和预期输出。等第一轮运行产生结果后,再补充详细的检查条件,也就是断言。

运行评测

核心方法是将每个测试用例运行两次:一次使用 Skill,一次不使用 Skill(或使用旧版本),从而获得可供比较的基线。

工作区结构

在 Skill 目录旁建立工作区目录,集中存放评测结果。完整评测循环的每一轮都使用独立的 iteration-N/ 目录。其中,每个测试用例又有自己的评测目录,内含 with_skill/ 和 without_skill/ 两个子目录:

csv-analyzer/
├── SKILL.md
└── evals/
    └── evals.json
csv-analyzer-workspace/
└── iteration-1/
    ├── eval-top-months-chart/
    │   ├── with_skill/
    │   │   ├── outputs/       # 本次运行生成的文件
    │   │   ├── timing.json    # token 数量与运行时长
    │   │   └── grading.json   # 断言检查结果
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    ├── eval-clean-missing-emails/
    │   ├── with_skill/
    │   │   ├── outputs/
    │   │   ├── timing.json
    │   │   └── grading.json
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    └── benchmark.json         # 汇总统计结果

需要手动编写的主要文件是 evals/evals.json。其他 JSON 文件(grading.json、timing.json、benchmark.json)在评测过程中由 Agent、脚本或你本人生成。

启动运行

每次评测都应从干净的上下文开始,不保留之前运行或开发 Skill 时的状态,以确保 Agent 只遵循 SKILL.md 提供的内容。在支持子 Agent 的环境中(例如 Claude Code),这种隔离可以自然实现:每个子任务都从全新状态开始。不支持子 Agent 时,为每次运行单独开启一个会话。

每次运行都需要提供:

  • Skill 路径(基线运行则不提供 Skill)
  • 测试 Prompt
  • 所需输入文件
  • 输出目录

以下是一次使用 Skill 的运行所需的指令示例:

执行以下任务:
- Skill 路径:/path/to/csv-analyzer
- 任务:我在 data/sales_2025.csv 中有一份月度销售数据。
  能找出营收最高的 3 个月,并制作一张柱状图吗?
- 输入文件:evals/files/sales_2025.csv
- 将输出保存到:csv-analyzer-workspace/iteration-1/eval-top-months-chart/with_skill/outputs/

基线运行使用同一条 Prompt,但不提供 Skill 路径,并将结果保存到 without_skill/outputs/。

改进已有 Skill 时,将旧版本作为基线。编辑前先保存快照(cp -r <skill-path> <workspace>/skill-snapshot/),让基线运行使用这份快照,并将结果保存到 old_skill/outputs/,而非 without_skill/。

记录耗时数据

耗时数据可以帮助比较使用 Skill 相较于基线增加了多少时间和 token 消耗。显著提升输出质量、但将 token 用量增至三倍的 Skill,与效果更好且成本更低的 Skill,需要作出不同的取舍。每次运行结束后,记录 token 数量与运行时长:

timing.json

{
  "total_tokens": 84852,
  "duration_ms": 23332
}

提示

在 Claude Code 中,子 Agent 任务完成后,任务完成通知会包含 total_tokens 和 duration_ms。应立即保存这些值,因为其他地方不会持久保存它们。

编写断言

断言是对输出应包含什么、应实现什么作出的可验证陈述。看到第一轮输出后再添加断言,因为 Skill 真正运行前,你往往还不知道“好结果”具体是什么样。

好的断言:

  • “输出文件是有效的 JSON”——可以用程序验证。
  • “柱状图的坐标轴有标注”——具体、可观察。
  • “报告至少包含 3 条建议”——可以计数。

价值较低的断言:

  • “输出很好”——过于模糊,无法评判。
  • “输出必须逐字使用‘Total Revenue: $X’这一表述”——过于僵硬,即使结果正确,只要措辞不同也会失败。

并非所有方面都需要断言。有些质量要求,例如写作风格、视觉设计、输出是否“合适”,很难拆成通过或失败的检查条件,更适合在人工审查中判断。断言应集中检查可以客观验证的内容。

在 evals/evals.json 中,为每个测试用例添加断言:

evals/evals.json

{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "我在 data/sales_2025.csv 中有一份月度销售数据。能找出营收最高的 3 个月,并制作一张柱状图吗?",
      "expected_output": "一张展示营收最高的 3 个月的柱状图图片,坐标轴和数值均有标注。",
      "files": ["evals/files/sales_2025.csv"],
      "assertions": [
        "输出包含一份柱状图图片文件",
        "图表恰好展示 3 个月",
        "两个坐标轴均有标注",
        "图表标题或图注提及营收"
      ]
    }
  ]
}

评判输出

评判输出,就是对照实际结果逐条检查断言,记录通过(PASS)或失败(FAIL),并附上具体证据。证据应引用或指向输出内容,不能只有主观判断。

最简单的方法是将输出和断言交给大语言模型(LLM),让它逐条评判。能够用代码检查的断言,例如 JSON 是否有效、行数是否正确、文件是否存在且尺寸符合预期,应交给验证脚本。对于机械性检查,脚本比 LLM 的判断更可靠,也便于在各轮迭代中复用。

grading.json

{
  "assertion_results": [
    {
      "text": "输出包含一份柱状图图片文件",
      "passed": true,
      "evidence": "在 outputs 目录中找到 chart.png(45 KB)"
    },
    {
      "text": "图表恰好展示 3 个月",
      "passed": true,
      "evidence": "图表展示了 3 月、7 月和 11 月对应的柱形"
    },
    {
      "text": "两个坐标轴均有标注",
      "passed": false,
      "evidence": "Y 轴标注为‘营收(美元)’,但 X 轴没有标注"
    },
    {
      "text": "图表标题或图注提及营收",
      "passed": true,
      "evidence": "图表标题为‘营收最高的 3 个月’"
    }
  ],
  "summary": {
    "passed": 3,
    "failed": 1,
    "total": 4,
    "pass_rate": 0.75
  }
}

评判原则

  • 判为通过必须有具体证据。 不能因证据不足就从宽认定。如果断言要求“包含摘要”,而输出只是有个“摘要”标题,下面仅有一句含糊的话,就应判为失败:只有标题,没有实质内容。
  • 同时审查断言本身,而不只看结果。 评判过程中,应注意哪些断言过于简单(无论 Skill 质量如何都通过)、过于苛刻(即使输出很好也总是失败),或无法验证(不能仅凭输出检查)。下一轮迭代前应修正这些断言。

提示

比较两个 Skill 版本时,可以尝试盲评:将两份输出交给担任评审的 LLM,但不告知它们分别来自哪个版本。评审模型按照自己的标准评价组织结构、格式、可用性和完成质量等整体表现,避免受到“哪个版本应该更好”的预期影响。这能补充断言评判:两份输出可能都通过所有断言,但整体质量仍有明显差别。

汇总结果

本轮所有运行都完成评判后,按配置计算汇总统计值,保存为评测目录旁的 benchmark.json,例如 csv-analyzer-workspace/iteration-1/benchmark.json:

benchmark.json

{
  "run_summary": {
    "with_skill": {
      "pass_rate": { "mean": 0.83, "stddev": 0.06 },
      "time_seconds": { "mean": 45.0, "stddev": 12.0 },
      "tokens": { "mean": 3800, "stddev": 400 }
    },
    "without_skill": {
      "pass_rate": { "mean": 0.33, "stddev": 0.10 },
      "time_seconds": { "mean": 32.0, "stddev": 8.0 },
      "tokens": { "mean": 2100, "stddev": 300 }
    },
    "delta": {
      "pass_rate": 0.50,
      "time_seconds": 13.0,
      "tokens": 1700
    }
  }
}

delta 表明 Skill 带来的成本(更多时间、更多 token)与收益(更高的通过率)。如果多用 13 秒就能将通过率提高 50 个百分点,通常值得;如果 token 用量翻倍,却只提高 2 个百分点,就未必值得。

注意

每个评测用例运行多次后,标准差(stddev)才有意义。早期迭代只有 2–3 个测试用例、每个仅运行一次时,重点应是实际通过数量和差值。随着测试集扩大、每个用例运行多次,这些统计指标才会更有价值。

分析规律

汇总统计可能掩盖重要规律。计算基准数据后:

  • 删除或替换两种配置下始终通过的断言。 它们无法提供有效信息,因为即使没有 Skill,模型也能处理好。它们会抬高使用 Skill 时的通过率,却不能体现 Skill 的实际价值。
  • 调查两种配置下始终失败的断言。 可能是断言有问题(要求模型完成做不到的事)、测试用例过难,或检查的目标不对。下一轮迭代前应先解决这些问题。
  • 研究使用 Skill 时通过、不使用时失败的断言。 这些地方明确体现了 Skill 的价值。要弄清原因:哪些指令或脚本产生了差别?
  • 多次运行结果不一致时,明确指令。 如果同一评测有时通过、有时失败(基准数据中的 stddev 较高),可能是评测不稳定,容易受到模型随机性的影响;也可能是 Skill 指令有歧义,模型每次理解都不同。可以添加示例或更具体的指导,减少歧义。
  • 检查耗时与 token 消耗的异常值。 如果某个评测耗时是其他评测的 3 倍,应阅读它的执行记录,也就是模型在本次运行中所有操作的完整日志,以找出瓶颈。

结合人工审查结果

断言评判和规律分析能发现不少问题,但只能覆盖你事先想到并写成断言的内容。人工审查能带来新的视角:发现未曾预料的问题,识别技术上正确却偏离需求的结果,或找出难以用通过、失败条件表达的问题。对每个测试用例,都应结合评判结果检查实际输出。

为每个测试用例记录具体反馈,保存到工作区中,例如在评测目录旁存为 feedback.json:

feedback.json

{
  "eval-top-months-chart": "图表缺少坐标轴标注,而且月份按字母顺序排列,没有按时间顺序排列。",
  "eval-clean-missing-emails": ""
}

“图表缺少坐标轴标注”能指导改进,“看起来不好”则不能。反馈为空表示输出没有明显问题,该测试用例通过了人工审查。在迭代环节,应重点改进那些有具体问题反馈的测试用例。

迭代改进 Skill

完成评判与审查后,可以获得三类反馈:

  • 失败的断言指出具体缺口,例如遗漏步骤、指令不清,或 Skill 没有处理某种情况。
  • 人工反馈指出更广泛的质量问题,例如方法不当、输出结构混乱,或结果虽然技术上正确,却没有实际帮助。
  • 执行记录揭示问题发生的原因。Agent 忽略某条指令,可能是因为指令有歧义;如果 Agent 把时间花在无效步骤上,相关指令可能需要简化或删除。

将这三类反馈连同当前的 SKILL.md 一起交给 LLM,请它提出修改建议,是把反馈转化为改进的有效方法。LLM 能综合失败断言、审查意见和执行行为,识别人工逐一关联时容易感到繁琐的规律。给 LLM 的 Prompt 应包含以下原则:

  • 从反馈中提炼普遍问题。 Skill 会用于许多不同的 Prompt,而不仅是这些测试用例。修改应普遍解决背后的问题,避免只为某个具体示例添加狭窄的补丁。
  • 保持 Skill 精简。 更少、更好的指令,往往胜过面面俱到的规则。如果执行记录显示存在无效工作,例如不必要的验证、无用的中间输出,就删除相关指令。如果不断增加规则,通过率却不再提高,Skill 可能受到过多约束。可以尝试删除指令,观察结果能否保持或改善。
  • 解释原因。 说明理由的指令(“执行 X,因为 Y 容易导致 Z”)通常比僵硬的命令(“始终执行 X,绝不执行 Y”)更有效。模型理解目的后,更能可靠地遵循指令。
  • 将重复工作封装为附带脚本。 如果每次测试都独立编写类似的辅助脚本,例如图表生成器、数据解析器,就说明应将该脚本放入 Skill 的 scripts/ 目录。具体方法参见使用脚本。

迭代循环

  1. 将评测反馈和当前的 SKILL.md 交给 LLM,请它提出改进建议。
  2. 审查并应用修改。
  3. 在新的 iteration-<N+1>/ 目录中重新运行全部测试用例。
  4. 评判并汇总新一轮结果。
  5. 结合人工审查,重复这一过程。

当结果令人满意、反馈持续为空,或各轮迭代之间已没有明显改善时,即可停止。

提示

skill-creator Skill 能自动完成这套工作流中的大部分环节,包括运行评测、检查断言、汇总基准数据,以及展示结果供人工审查。