Skill Eval

---
name: skill-eval
description: >-
  Behaviorally evaluate a skill in two modes: pass-rate (define 3-5 representative tasks,
  run each N>=3 times with and without the skill loaded in fresh agents, compare pass
  rates) and trigger rate (build ~20 queries — 8-10 should-trigger plus 8-10 near-miss —
  run each 3 times, score per-query trigger rate). Both report a table plus concrete
  improvement items that feed back into the skill's SKILL.md. Use when a skill changes, at
  quarterly evaluation, when accepting a new skill, or when description triggering looks
  unreliable. Because it writes back into other skills' SKILL.md it is USER-INVOKED ONLY:
  the agent must not auto-invoke it — the user runs it explicitly. NOT for: static
  description-vs-body compliance review of a SKILL.md.
slug: skill-eval
version: 1.2.0
displayName: skill-eval
disable-model-invocation: true
---

# Skill Eval（高频 skill 动态评估：行为 pass-rate ＋ 触发率）

## 定位

高频 process skill 的**动态评估**，两模式互补：① **行为 pass-rate**（有/无 skill 各跑 N 次 → 对比 → 失败案例反哺正文）；② **触发率 trigger rate**（描述在该触发时是否触发、不该触发时是否误触发）。与 `skill-description-audit`（静态描述合规）互补。

## 何时使用

- skill 变更后（行为是否真变好）
- 季度评估（基线节奏）
- 新 skill 验收（交付后先建基线）
- 描述触发不可靠时（应触发不触发／误触发）

## 输入

- 目标 skill（首批：code-review / project-handoff / writing-plans / stage-gate）
- 评估记录目录：`.scratch/neonforge-v1/skill-eval/<skill>-<YYYY-MM-DD>/`

## 流程

```
- [ ] 1. 定义代表任务：3-5 个（见下节）
- [ ] 2. 无 skill 基线：每任务跑 N 次（N≥3，fresh agent、无对话种子）
- [ ] 3. 有 skill 组：同任务同 prompt 跑 N 次（fresh agent + 加载目标 skill 指令）
- [ ] 4. 逐次判定 pass/fail（按任务 AC，机器可验证优先——文件存在/输出匹配/命令结果）
- [ ] 5. 汇总 pass-rate 对比表（任务 | 无 skill | 有 skill | Δ）
- [ ] 6. 失败案例分析：成功/失败样例各取代表，定位 skill 改进点
- [ ] 7. 产出报告 + 改进项写回 skill SKILL.md（或作为下轮验收项）
- [ ] 8. 结果入 SKILLS-MAP 或该 skill README（基线表）
```

## 代表任务定义（3-5 个）

每个任务 = 一段**独立 prompt** + 可判定的 AC：

| 要求 | 说明 |
|------|------|
| 覆盖核心能力 | 任务必须命中 skill 的标志性能力（如 stage-gate 的「跑 S{N} 门禁」） |
| 有代表性失败模式 | 选任务时预判「无 skill 会怎么错」（漏验证/散文断言/只验不修） |
| AC 机器可验证 | 优先：文件存在且含 X / 命令输出匹配 / 断言数正确；次选：结构化报告字段齐全 |
| 现实规模 | 用真实仓库的最小场景（同仓库 fixture），不用玩具示例 |

## 运行纪律

- **fresh agent**：每组每次都是新会话（无对话种子）——防记忆污染；有 skill 组只多加载目标 skill 指令，其余提示词逐字一致。
- **同 prompt 逐字一致**：两组差异仅「是否加载 skill」。
- **判定者独立于执行者**：pass/fail 由 AC 判定，不看「agent 自报成功」（verification-before-completion）。
- 记录：每次运行的任务 prompt、AC、产物路径、判定——落盘评估目录，报告可复核。

## 报告（pass-rate 对比表）

```markdown
# Skill Eval: {skill}（{date}）

| 任务 | 无 skill (N) | 有 skill (N) | Δ | 结论 |
|------|-------------|-------------|---|------|
| 任务 1 | 1/3 | 3/3 | +2 | skill 有效 |
| 任务 2 | 2/3 | 2/3 | 0 | 无效/无差异——改进点：… |

## 失败案例分析（反哺）

- 有 skill 仍失败 ×2 → 改进项：{具体到 SKILL.md 哪节缺什么}

## 改进项（低分 skill 必出）

1. …（具体、可验收）
```

## 动态触发实测（trigger-eval）

评估「描述在该触发时触发、不该触发时不触发」。方法（agentskills.io《Optimizing skill descriptions》）：

- [ ] 1. **查询集 ~20 条**：8–10 条**应触发**（点名该 skill 能力的真实请求）＋ 8–10 条**近似不应触发**（话题相邻但属别的技能／无技能）。
- [ ] 2. 每条跑 **3 次**（fresh agent，仅带该技能描述面），**trigger rate** ＝ 触发次数/3，阈值 **0.5**。
- [ ] 3. 按 **60/40** 切 **train / validation**；只据 train 改 description，在 validation 上复测（防过拟合）。
- [ ] 4. 迭代约 **5 轮**：改 description（补 WHEN／加反触发）→ 重跑 → 直到 validation 上应触发组全过、不应触发组全不触发。
- [ ] 5. 落盘 `.scratch/<项目>/skill-eval/<skill>-trigger-<YYYY-MM-DD>/`（查询集＋逐次结果）；报告附 trigger rate 表。

判读：应触发组漏触发 → WHEN 过窄／触发词缺；不应触发组误触发 → WHEN 过宽／缺反触发。静态面另有跨技能混淆闸 `scripts/trigger-confusion-test.py`（T1/T2/T3）——它不替代本节的按查询集实测。

## 验收

- [ ] 每任务有/无 skill 各 N≥3 次（总计 ≥6 次/任务），记录落盘
- [ ] 输出 pass-rate 对比表（含 Δ 与结论）
- [ ] 低分 skill（有 skill 无显著提升或仍失败）得到具体改进项
- [ ] 触发实测（如做）：查询集 ~20（含 8–10 近似反例）、每查 3 跑、trigger rate 表＋validation 复测
- [ ] 改进项已反馈（写回 SKILL.md 或列入下轮验收）
- [ ] 基线结果入 SKILLS-MAP / skill README

## 边界（分工）

| 相邻技能 | 分工 |
|---------|------|
| `skill-description-audit` | 静态描述合规（description↔正文）；skill-eval = 动态（pass-rate ＋ trigger rate）——先合规后行为 |
| `verification-before-completion` | 判定纪律来源（AC 证据判定，不信自报） |
| `delegated-research` | 不适用——评估是受控实验，不是调研 |

## 最短真实样例

**前置**：目标 skill `writing-plans` 在库内（`ls writing-plans/SKILL.md` 可解析）；评估目录可建；3 个代表任务已带 AC 定义。

**调用句**（用户点名）：

> 用 skill-eval 评估 writing-plans，每任务跑 3 次

**产出摘录**（评估目录里 `report.md` 的核心表）：

```markdown
# Skill Eval: writing-plans（2026-09-29）

| 任务 | 无 skill (N) | 有 skill (N) | Δ | 结论 |
|------|-------------|-------------|---|------|
| 拆 12 步迁移计划 | 1/3 | 3/3 | +2 | skill 有效 |
| 补验收 AC | 2/3 | 2/3 | 0 | 无差异——改进点：AC 节缺「机器可验证」示例 |

## 改进项
1. writing-plans/SKILL.md「验收」节补 1 条机器可验证 AC 示例（文件含 X / 命令退出码）
```

触发率模式摘录（同一报告附表）：查询集 20 条、每条 3 跑；应触发组 trigger rate 0.83（漏 1 条→WHEN 缺「对比评审」触发词）、不应触发组 0.00。

## 失败出口（可操作，非「降级标注」）

| 情形 | 可观察信号 | 出口 |
|------|-----------|------|
| 目标 skill 名不对 | `ls <name>/SKILL.md` 非零退出 | 停止评估，列出库内近名技能请用户确认；不得猜名开跑 |
| 无法开 fresh agent（只有单一会话） | 无新建会话手段 | 报告「本环境不可评估」并终止——两组条件不一致的结论比没有结论更有害，禁止降级出表 |
| AC 无法机器验证 | 判定只能凭阅读/感觉 | 停在该任务，与用户重写 AC（改成文件存在/输出匹配/命令退出码）；其余可判任务照常 |
| 评估目录写不进 | 落盘命令非零退出 | 换 `.scratch/<项目>/skill-eval/<skill>-<date>/` 下可用路径并在报告头注明实际路径 |
| 触发实测无网（需拉取环境/模型不可用） | 每条查询 3 跑均无法产生结果 | 只交付 pass-rate 模式报告，触发率节标注「未执行：环境不可用」——不编造触发次数 |

## 错法 → 改法

| 错法 | 改法 |
|------|------|
| agent 不等用户点名，自主跑评估并改他人 SKILL.md | 本技能 USER-INVOKED ONLY：只在用户显式调用时运行；改写前先出报告征得用户确认 |
| 同一会话先后跑两组 | 每组每次 fresh agent；发现同会话即作废已跑数据重跑 |
| 两组 prompt 有细微差别（多塞了一句提示） | 两组 prompt 逐字一致，唯一差异＝是否加载 skill 指令 |
| pass/fail 采信 agent 自报成功 | 只按 AC 证据判定（命令退出码/文件内容），自报不作为证据 |
| 在 validation 查询集上调完 description 再报结果 | 只据 train 集改 description；validation 仅复测，结果并入报告 |
| 触发查询集 20 条全是正例 | 必含 8–10 条近似反例，否则误触发测不出 |

## 边界判定句

- 无仓／无目标 skill：`ls <name>/SKILL.md` 非零 ＝ 错仓或错名，不评估。
- 单会话、无法 fresh agent ＝ 不可评估（见失败出口第 2 行），不是「尽力而为」。
- 目标 skill 属于审计/发布/删除类高影响技能时，其行为评估照常，但写回改进项前须用户显式授权（AGENTS.md 规则 7）。

## 反模式

- N<3 或两组条件不一致（结论无统计意义）
- 用同一会话跑两组（skill 指令泄漏到基线组）
- 判定凭「感觉」不按 AC（自报成功当 pass）
- 只报对比不反哺（评估完 skill 没变好）
- 任务不覆盖标志性能力（评估了但没评估到点子上）
- 触发查询集全是正例（无近似反例）——测不出误触发
- 用 train 集自评（读了 validation 再改 description＝过拟合）