评估 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/目录。具体方法参见使用脚本。
迭代循环
- 将评测反馈和当前的
SKILL.md交给 LLM,请它提出改进建议。 - 审查并应用修改。
- 在新的
iteration-<N+1>/目录中重新运行全部测试用例。 - 评判并汇总新一轮结果。
- 结合人工审查,重复这一过程。
当结果令人满意、反馈持续为空,或各轮迭代之间已没有明显改善时,即可停止。
提示
skill-creatorSkill 能自动完成这套工作流中的大部分环节,包括运行评测、检查断言、汇总基准数据,以及展示结果供人工审查。