<!-- title: Skill评测基准：从祈祷到工程化 -->

## 概述

本教程教你用 Claude Code 官方 **skill-creator** 插件的评测体系，给自定义 Skill 跑测试、做基准对比、调优触发描述。学完你将掌握：编写 `evals.json` 测试用例、并行隔离运行 eval、A/B 盲评对比「有 Skill / 无 Skill」、跑多轮 benchmark 拿到通过率/Token/耗时指标、迭代修复薄弱点。适用人群：已经写过至少一个 `SKILL.md`、想把「写完祈祷能用」升级为「用数据证明有用」的开发者。

## 前置条件

- 已安装 Claude Code（CLI 或 IDE 插件），版本支持插件市场（2026 年 3 月 skill-creator 增强之后）。
- 在终端执行 `/plugin` 能搜到官方 **skill-creator** 插件并安装。
- 手头有一个待测的 Skill 目录，形如 `.claude/skills/<name>/SKILL.md`；没有的话，本教程会附带一个最小可运行示例。
- 基础的 Markdown 与 JSON 阅读能力；全程自然语言驱动，**无需写任何测试代码**。

## 一、先认清问题：Skill 为什么要评测

很多开发者写 Skill 的真实流程是：写 `SKILL.md` → 手测一两次 → 发布 → 默默祈祷。两个问题随之而来，且都没有答案：

1. **该触发的时候触发了吗？**（召回率 / 漏触发）
2. **触发之后，输出真的比裸 Claude 好吗？**（质量增益）

`SKILL.md` 本质是一段文本指令。当底层模型更新，它解读这段指令的方式会漂移——上周还能稳定揪出 SQL 注入的代码审查 Skill，换了个模型版本可能就开始漏报。你不会知道，除非你测。

官方把 Skill 分成两类，评测侧重点不同，先对号入座：

| Skill 类型 | 定义 | 典型例子 | 评测重点 |
|---|---|---|---|
| **能力增强型**（Capability uplift） | 让模型做到原本做不到或不稳定的事 | 文档生成、PDF 填表 | 输出质量是否达标；模型进步后是否已不必要 |
| **偏好编码型**（Encoded preference） | 模型本就会做，Skill 负责按团队流程编排 | NDA 审查流程、周报模板 | 是否严格遵循规定流程与格式 |

能力增强型对模型更新更敏感，是 benchmark 的重点对象；偏好编码型更耐用，但价值取决于「对真实工作流的保真度」。

## 二、安装 skill-creator 并理解四种模式

在 Claude Code 会话里输入 `/plugin`，搜索 `skill-creator`，安装官方 Anthropic 插件。安装后，skill-creator 提供四个核心模式，全部用自然语言触发：

| 模式 | 触发语 | 作用 |
|---|---|---|
| **Create** | "create a skill for X" | 从零生成 `SKILL.md` |
| **Eval** | "eval my `<name>` skill" | 对测试用例打分，输出 pass/fail |
| **Improve** | "improve my `<name>` skill" | 两版本盲评 A/B 对比 |
| **Benchmark** | "benchmark my `<name>` skill, N runs" | 多轮统计：通过率均值±标准差、Token、耗时 |

记住一句话就够：**「用 skill-creator 来 XXX 我的某个 skill」**，它会自动切到对应模式。

## 三、编写 evals.json：测试用例的灵魂

评测的质量由测试用例决定。一份合格的 eval 集，要同时包含**正向提示**（应触发、应达标）和**负向提示**（不该触发）。下面是贯穿全文的示例 Skill——一个 PR 安全审查 skill `pr-sec-review` 的 eval 草案：

```json
{
  "skill": "pr-sec-review",
  "tests": [
    {
      "id": "t1-sqli",
      "prompt": "审查这个 Python 函数的安全问题",
      "file": "samples/get_user.py",
      "expect": "应识别 get_user() 中字符串拼接 SQL 注入风险，并建议参数化查询"
    },
    {
      "id": "t2-secrets",
      "prompt": "检查我的 git diff 再提交",
      "file": "samples/diff-with-key.patch",
      "expect": "应抓出第 42 行硬编码 API key，建议改用环境变量"
    }
  ],
  "negatives": [
    { "prompt": "给我的项目写一份 README" },
    { "prompt": "帮我 debug 这个报错" }
  ]
}
```

关键在于 `expect` 要**可判定**。「给出好的反馈」不是合格标准；「识别 async handler 里的竞态条件，并建议用互斥锁」才是。每个用例可以挂一组断言（assertions），用布尔判定：

- `has_severity_ratings` —— 发现必须按严重级别归类
- `identifies_unsanitized_input` —— 必须标出第 126 行的未过滤 `$_POST`
- `no_false_positives_on_safe_hooks` —— 不得把已知安全的钩子误报为缺 nonce
- `includes_passed_checks` —— 必须列出**通过**的检查项，而不只是缺陷

> 常见坑：**只测 happy path**。只喂有明显 bug 的代码，你永远不知道 Skill 面对干净代码或隐蔽问题时表现如何。务必加边界用例和负向用例。

## 四、运行 Eval：并行隔离 + 盲评

告诉 Claude：

```
用 skill-creator 来 eval 我的 pr-sec-review skill
```

skill-creator 会启动多个独立子 agent 并行跑，**每个都在干净的隔离上下文里**——这一点至关重要，它防止上一个测试的输出污染下一个。典型的一次 A/B 评测会并行拉起 6 个 agent：

- 3 个带 Skill 跑测试用例
- 3 个不带 Skill（baseline 裸 Claude）跑同样用例

跑完后，输出交给一个**比较器 agent** 做**盲评**——它不知道哪份输出来自带 Skill 的版本，只按质量打分。这能消除作者偏见：不是你自说自话「我的改动有帮助」，而是独立 agent 只看产出质量判定。

预期结果会汇总成一张对比表，形如（数据来自一次真实 WordPress 安全审查 Skill 评测）：

| 指标 | 带 Skill | Baseline | 差值 |
|---|---|---|---|
| 通过率 | 100%（21/21） | 90.5%（19/21） | **+9.5%** |
| 平均 Token | 74,427 | 69,734 | +6.7% |
| 平均耗时 | 276s | 307s | 快 9.9% |

注意这个反直觉的结论：**更彻底的 Skill 反而更快**——因为它有结构化清单，不用边走边想。baseline 漏掉的，往往是业务逻辑一致性问题（某条路径有校验、另一条没有）。

## 五、跑 Benchmark：拿到稳定基线

单次 eval 不说明问题，模型行为本身有方差。benchmark 模式把同一套 eval 跑 N 轮，报告聚合统计：

```
用 skill-creator 来 benchmark 我的 pr-sec-review skill，跑 5 轮
```

你会拿到三个指标：

- **通过率均值 ± 标准差**（如 85% ± 5%）—— 衡量稳定性。一次 100%、下一次 60% 的 Skill，即使均值好看也是隐患。
- **Token 用量**—— 一次该花 2k Token 却花了 8k，说明指令太啰嗦或触发了多余推理。
- **耗时**—— 接入 CI 或团队流水线时重要。

benchmark 的真正价值是**建立基线**：今天存下这组数字，下次模型升级后重跑。若通过率从 90% 掉到 70%，你就知道是更新引入了回归，且能精确定位是哪些用例挂了。官方建议：**模型发布一周内重跑 benchmark**，跌幅超 10 个百分点就排查修复。

## 六、调优触发描述：减少误触与漏触

评测只能衡量「触发后」的质量，但前提是**它在该触发时触发、不该触发时安静**。Skill 越多，描述精确度越关键：

```
用 skill-creator 来优化我的 pr-sec-review skill 的触发描述
```

它会生成「应触发」与「不应触发」两类提示，逐个测试你的 `description` / `when_to_use`，迭代后给出修订版描述。官方在自己的文档生成类 Skill 上跑过，6 个里有 5 个触发更准。

两个调优要点：

1. **描述要「稍微强势一点」**。Claude 倾向于在 Skill 确实有用时也少用，所以写「在提交前审查暂存的 git 改动，覆盖安全、逻辑、风格问题」比写「帮忙做代码审查」触发率更高。
2. **同时盯召回与精确**。只测正向会漏报「漏触发」（低召回）；不加负向用例就测不出「误触发」（低精确）。一个高召回但低精确的 Skill 会在每个无关请求上白白烧 Token。

## 七、迭代修复：eval → fix → re-eval 闭环

这是整个体系最有价值的部分。eval 结果会**指出具体弱点**，Claude 据此做外科手术式的 `SKILL.md` 修改：

- baseline 反而抓到了 JS 里的 DOM XSS → 给 Skill 加「扫描 JavaScript 文件的 DOM 型 XSS」。
- `wp_unslash` 在数字字段上的严重级别标得不一致（HIGH/MEDIUM 摇摆）→ 校准为 Low。
- 业务逻辑一致性检查最有价值 → 加「校验在一条路径有、另一条没有」的检测模式。

改完**立刻重跑 eval** 验证。大多数 Skill 会从首评约 60% 的通过率，经两三轮迭代升到 90%+。改之前先用 improve 模式做 A/B，留下 before/after 对比，防止「修好这个、弄坏那个」的回归。

整体工作流可视化如下：

```mermaid
flowchart TD
    A[编写/已有 SKILL.md] --> B[编写 evals.json<br/>正向+负向用例+断言]
    B --> C[Eval 模式<br/>并行隔离子agent打分]
    C --> D{通过率达标?}
    D -- 否 --> F[Improve 模式 A/B<br/>比较器盲评找弱点]
    F --> G[外科手术式修改 SKILL.md]
    G --> C
    D -- 是 --> E[Benchmark 模式 N轮<br/>建立基线:通过率/Token/耗时]
    E --> H[Trigger 优化<br/>减少误触与漏触]
    H --> I[模型更新后重跑<br/>对比基线查回归]
    I --> C
```

评测运行时的并行隔离架构：

```mermaid
flowchart LR
    Q[evals.json 测试集] --> S1[子agent1 隔离上下文 带Skill]
    Q --> S2[子agent2 隔离上下文 带Skill]
    Q --> S3[子agent3 隔离上下文 带Skill]
    Q --> B1[子agent4 隔离上下文 无Skill-baseline]
    Q --> B2[子agent5 隔离上下文 无Skill-baseline]
    Q --> B3[子agent6 隔离上下文 无Skill-baseline]
    S1 & S2 & S3 & B1 & B2 & B3 --> J[比较器agent<br/>盲评-不知来源]
    J --> R[对比报告<br/>通过率/Token/耗时]
```

## 八、实战案例：一个可运行的 pr-sec-review 闭环

下面给出从零到出报告的最小可运行链路。

**1. 最小 Skill（`.claude/skills/pr-sec-review/SKILL.md`）核心片段：**

```markdown
---
name: pr-sec-review
description: 在提交或合并前审查 git 改动与代码片段的安全、逻辑、风格问题，输出带严重级别标注的结构化报告。当用户提交代码审查、检查 diff、或担心注入/密钥泄露时主动使用。
---
## 流程
1. 定位待审查文件（git diff 或指定文件）
2. 逐类检查：注入、密钥、未授权访问、业务逻辑一致性
3. 输出：[严重级别] 问题 + 已通过项 + 修复建议
```

**2. 触发评测：**

```
用 skill-creator 来 eval 我的 pr-sec-review skill，evals 见 .claude/skills/pr-sec-review/evals.json
```

**3. 预期首轮结果（典型）：** 通过率约 60%，常挂在「漏抓硬编码 key」「误报安全钩子缺 nonce」两项。

**4. Claude 自动建议修改并重跑：** 加「扫描 sk-/AKIA/ghp_/xox- 等常见密钥格式」步骤；加「已知安全钩子白名单」。

**5. 跑 benchmark 建立基线：**

```
用 skill-creator 来 benchmark 我的 pr-sec-review skill，跑 5 轮
```

**6. 决策：** 若最终通过率稳定 90%+ 且耗时低于 baseline，发布；否则继续 improve 闭环。

把 `evals.json` 与 `expected` 存进 Skill 目录，团队任何人都能复现评测，而不只是原作者凭记忆手测。

## 九、常见问题与排错

- **Q：Skill 通过率很高但 Token 暴涨。** A：指令太啰嗦。一个本该 2k Token 的事花了 15k，检查是否触发了多余推理，精简指令。
- **Q：A/B 时 baseline 反而赢了。** A：说明该 Skill 可能是「能力增强型」且模型已进步到不需要它——考虑退役或收窄为「偏好编码型」。
- **Q：只测一次就上线。** A：单次过不了稳定性关。能力增强型务必 benchmark 多轮。
- **Q：负向用例缺失。** A：没有「不应触发」的提示，就测不出误触发，Skill 会在无关请求上烧 Token。
- **Q：eval 结果说「漏抓某模式」。** A：让它告诉你具体哪条用例、哪行，据此加针对性步骤，再 re-eval，形成闭环。

## 延伸阅读

- [Improving skill-creator: Test, measure, and refine Agent Skills（Anthropic 官方）](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) — 官方宣布 eval/benchmark/A/B/触发优化四大能力的原文。
- [Extend Claude with skills（Claude Code 官方文档）](https://code.claude.com/docs/en/skills) — Skill 创建、管理、分发的权威参考。
- [Claude Code Skill Creator: How to Test and Benchmark Your Skills](https://www.nathanonn.com/claude-code-skill-creator-guide/) — WordPress 安全审查 Skill 的完整实战复盘，含真实 benchmark 数据。
- [How to Eval and Benchmark SKILL.md Skills (2026 Guide)](https://www.agensi.io/learn/how-to-eval-benchmark-skill-md) — 四种模式与五步流程的详细操作指南。

## 参考来源

1. [Improving skill-creator: Test, measure, and refine Agent Skills](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) — Anthropic 官方产品公告（2026-03-03），两类 Skill 定义、eval/benchmark/触发优化、并行隔离与盲评机制。
2. [How to Eval and Benchmark Your SKILL.md Skills (2026 Guide)](https://www.agensi.io/learn/how-to-eval-benchmark-skill-md) — Create/Eval/Improve/Benchmark 四模式操作手册，五步首跑流程与常见错误清单。
3. [Claude Code Skill Creator: How to Test and Benchmark Your Skills](https://www.nathanonn.com/claude-code-skill-creator-guide/) — 真实 WordPress 安全审查 Skill 全流程实战，含 100% vs 90.5% 基准对比与并行 6-agent 细节。
4. [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills) — 官方 Skill 体系与 `SKILL.md` 格式权威文档。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)