Skill 评估体系：Sentry Skills 的 EVAL.md 与 evals 场景化验证方法完整指南

Skill 评估体系是 Sentry Skills 仓库（Sentry 团队内部使用的 Agent Skills 集合）中一套"给 AI 技能做体检"的工程化方法。简单来说：每当你修改了一个 Skill（一份教 AI Agent 做事的 Markdown 说明书），光靠"我读了觉得没问题"是不够的——你需要让它真正跑一遍真实任务，再看产出是否合格。这套方法由两部分组成：一份面向维护者的操作手册EVAL.md，加上一组可重复执行的evals/场景测试用例。

下面用最短的篇幅，讲清楚这套评估体系如何搭建、如何运行、如何判断结果。

为什么要给 Skill 做评估？

Skill 本质是写给 AI 的"操作手册"。手册写得再顺眼，也可能在实际任务中翻车：

• 触发不准：该激活时不激活，不该激活时乱插嘴；
• 产出失控：生成的文档啰嗦、模板味重、夹带无关内容；
• 悄悄退化：这次改好了 A，下次却把上次修好的 B 改坏了。

💡 类比：Skill 是产品代码，evals/就是它的自动化测试用例，而EVAL.md是"测试运行手册"。

Sentry Skills 仓库里有 20 多个 Skill（code-review、commit、security-review等，完整清单见 README.md），其中两个核心 Skill 配了完整的评估体系：

EVAL.md 是什么：一份"评估操作手册"

EVAL.md不是给 AI 看的运行时文件，而是给人类维护者看的 playbook。以 skills/skill-writer/EVAL.md 为例，它回答四个问题：

1. 用什么框架跑？仓库选型为 AXIS（@netlify/axis，MIT 开源），原因很务实：内置 Codex 适配器、隔离工作区、LLM 评分器、报告与基线对比，一个都不缺。
2. 怎么快速跑起来？每条命令都写好了（见下文"一键运行评估命令"一节）。
3. 测什么、怎么判？给出"测试层级表"（结构、确定性检查、模型评审）和一套评分量表（Rubric）。
4. 什么时候允许合并？明确的Adoption Gate（采纳门槛）检查清单。

还有一个关键设计原则：评估文件不参与运行时路由。也就是说SKILL.md正文不会链接到自己的EVAL.md——AI 干活时不需要知道"自己怎么被考"，除非用户明确说"跑一下评估"。这一点在 skills/skill-writer/references/skill-evals.md 里被单独强调。

目录结构：evals 场景化验证的文件布局

每个被评估的 Skill 下都有统一的三件套：

skills/<skill-name>/ ├── EVAL.md # 维护者手册：怎么跑、怎么判 └── evals/ ├── axis.config.json # AXIS 运行配置 └── scenarios/ # 一个个"考试题目"（JSON 场景文件）

各文件分工如下（引自 skills/skill-writer/references/skill-evals.md）：

以 skills/skill-writer/evals/axis.config.json 为例，配置只做三件事：

• 指定被测试的 Agent（"agent": "codex"，开启full-auto全自动模式）；
• 通过"skills": ["./.."]把当前这个本地 Skill装进测试环境——考的就是你正在改的东西；
• 设置超时（单场景 15 分钟），卡住时快速失败、方便调试。

一键运行评估：四条核心命令

所有命令都写在各自的EVAL.md里，以skill-writer为例（skills/skill-writer/EVAL.md）：

1️⃣ 跑完整工作集

npx @netlify/axis run --config skills/skill-writer/evals/axis.config.json

2️⃣ 只跑单个用例（调 bug 时最常用）

npx @netlify/axis run \ --config skills/skill-writer/evals/axis.config.json \ --scenario small-inline-workflow

3️⃣ 查看报告（加--html可生成网页版报告）

npx @netlify/axis reports latest --config skills/skill-writer/evals/axis.config.json

4️⃣ 与基线对比（判断是否退化的关键一步）

npx @netlify/axis run \ --config skills/skill-writer/evals/axis.config.json \ --compare-baseline

⚠️ 基线（baseline）只在人工审阅报告之后才允许刷新：npx @netlify/axis baseline set。先信人、再信机器。

场景用例详解：一道"考试题"长什么样

每个场景是一个 JSON 文件，放在evals/scenarios/下，由四部分构成：

案例 1：small-inline-workflow（skills/skill-writer/evals/scenarios/small-inline-workflow.json）

任务很简单：请 Agent 创建一个"发布说明润色器"小技能。真正的考点藏在检查项里——它故意只要求简单，如果 Agent 过度拆分、为一条小规则硬造references/目录，就会被扣分。这类用例专门抓"过度工程"。

案例 2：iteration-from-bad-output（skills/skill-writer/evals/scenarios/iteration-from-bad-output.json）

setup 阶段会人为植入一个烂 Skill：触发范围过宽的csv-cleaner、臃肿的SKILL.md、一条规则一个文件的碎片化 references。任务要求 Agent 把它改精准、改紧凑。评分项甚至检查"改进是否泛化自负面证据，而不是只会改这几句词"。这是对迭代能力的直接考察。

案例 3：concise-docs-pr（skills/pr-writer/evals/scenarios/concise-docs-pr.json）

针对pr-writer：setup 先给 skills/pr-writer/SKILL.md 追加一段"文档型变更要写简短 PR"的指引并提交，然后让 Agent 为这段未提交的改动起草 PR 标题和正文。四条 judge 检查项（权重 0.3 / 0.3 / 0.2 / 0.2）分别盯：标题是否用合规的 conventional commit 类型、正文是否面向评审人且不啰嗦、有没有残留Summary/Test Plan模板标题、有没有倾倒验证命令输出。

📌 三个用例正好构成最小评估集的黄金组合：正常路径（happy path）、防过度工程、从坏输出中迭代——这正是 skills/skill-writer/references/skill-evals.md 建议的"最小用例集"模式。

判分方法：确定性检查 + LLM 裁判 + 人工量表

评估不是"AI 打个分就完事"，而是三层防线：

1. 确定性断言：文件是否生成、引用是否解析、验证器是否通过——客观事实，机器判；
2. LLM 裁判（judge 检查项）：简洁度、结构、来源覆盖等开放式质量——但裁判必须引用证据（路径、diff、转录片段），不许空口给分；
3. 人工量表（Rubric）：EVAL.md中定义了七个维度，每个维度打pass/warn/fail：

其中前五个是关键维度——任何一项在保留用例上退化，就不得合并。

另外两个值得学习的方法论细节：

• 盲比（blind old-vs-new comparison）：分数接近时，让裁判不知道哪份是新版，避免"新版本光环效应"；
• 看转录找病根：运行失败或异常慢时，去翻 transcript——浪费的步骤往往指向指令臃肿或含糊。

采纳门槛：什么时候才允许合并

两份EVAL.md都定义了清晰的 Adoption Gate。以 skills/skill-writer/EVAL.md 为例，必须同时满足：

1. 工作集 AXIS 运行全部完成；
2. 关键维度在保留用例上无退化；
3. 至少有一个目标维度在"引发本次修改的用例"上改善；
4. 结构性验证通过（或转录里能解释合理阻塞）；
5. 运行时SKILL.md保持路由器定位，不链接评估文件；
6. 只有技能契约变化时才更新来源与维护说明。

跑完后还要按EVAL.md里的结果模板输出一份摘要：基线 vs 候选、报告位置、用例结果表、关键退化、最终决策（adopt/revise/reject）。没有这份摘要，评估等于没做。

8 条评估原则速记

s skills/skill-writer/EVAL.md 沉淀的评估原则，浓缩成新手可直接套用的 8 条：

1. 先写 2-3 个真实用例，再谈扩展；
2. 用基线对比，别信单次分数；
3. judge 检查项要可观察：文件建没建、禁用的文件在不在、验证跑没跑；
4. 开放式质量交给 LLM 裁判；
5. 每个检查项和人工评审都要有具体证据；
6. 盯住耗时、token 消耗和无效交互；
7. 失败或变慢就去读转录；
8. 分数接近时用盲比裁决。

上手清单：从零搭建一套 Skill 评估

想给自己项目的 Skill 配上同款体系？照这张表抄作业即可：

1. 在 Skill 目录下建EVAL.md+evals/目录；
2. 写最小axis.config.json：指定 agent、"skills": ["./.."]、场景超时；
3. 按"正常路径 + 边缘/安全 + 反模式纠正"三件套写第一批场景，放到evals/scenarios/；
4. 每条 judge 检查项都写成"可观察 + 带权重"，长素材放evals/fixtures/而不是塞进 prompt；
5. 首次跑通后设基线，此后每次改动都--compare-baseline；
6. 人工按 Rubric 打分，过 Adoption Gate 才合并。

✅ 整套方法论的核心只有一句话：Skill 的修改必须用可重复的真实任务来验证，且决策要同时机器证据与人工量表支撑。

相关文件索引

掌握这套EVAL.md+evals/场景化验证方法，你就能像 Sentry 团队一样，让每一个 Skill 的迭代都"有考可出、有据可查、有门可过"。