Skill Quality — Agent Skill 质量审查

入口/出口

• 入口: 新增或修改中的 SKILL.md、技能辅助 .md、技能路由描述、触发样本或任务样本
• 出口: 可路由、可加载、可验证、可维护的 Skill 合同；必要时同步 skills-index.json、skills-router.json、skills-lock.json
• 指向: 通过 → 回到原阶段；不通过 → 退回修改 Skill 合同后重审
• 前置加载: CANON.md；修改本仓库技能时还必须读取目标技能全文
• 输出路径: Skill 质量报告可并入 docs/features/<name>/04-review.md 或当前任务的验证记录

何时不使用

• 用户只是要求解释某个业务概念，不涉及 Skill 创建、修改、路由或审查
• 用户只是要求使用现有 Skill 完成任务，没有发现 Skill 合同问题
• 目标是一般代码质量审查，应使用 verify-quality-code-quality
• 目标是项目文档质量，应使用 reflect-team-documentation 或内容审查技能

Iron Law

<HARD-GATE> Skill 是上下文路由合约，不是长提示词。 任何 Skill 修改必须回答四个问题：什么时候触发、触发后怎么做、什么时候停止、如何判断做对。 没有明确 description 触发边界、STOP 条件、输出契约和验证清单的 Skill 不得批准。 </HARD-GATE>

核心锚点

• Context-Dense Skill: 每个 token 都必须减少误触发、降低错误路径或提升执行稳定性。
• Routing Contract: description 说明何时必须加载和 near-miss 排除边界，不写成简介。
• Progressive Disclosure: 高频规则留在 SKILL.md；长案例、长 checklist、理论解释放辅助文件；确定性重复逻辑放 scripts。
• Gotchas First: 优先写本地规则、反直觉约束、失败案例和红旗，删除模型已知道的通用知识。
• Output Contract: 执行型和治理型 Skill 必须稳定输出结构，不能让 agent 自由发挥。
• Eval-Driven Development: description 和流程变更必须有 Trigger Eval 与 Task Eval 视角，至少覆盖 near-miss。

审查流程

Step 1：定位 Skill 类型

先判断 Skill 改变哪类行为：

如果定位过宽，先收窄。宁可窄而稳，不要宽而虚。

Step 2：审查 description

description 必须在 body 加载前完成路由判断。检查：

• 是否写明真实用户意图，而不是内部实现机制
• 是否包含典型触发词和隐含意图
• 是否排除 near-miss，例如“设计 API 合同”触发，“实现 API 代码”不触发
• 是否避免 “all backend development” 这类过度承诺

不合格 description 先修 description，再审正文。

Step 3：删掉低密度内容

逐段提问：没有这段，agent 是否更容易做错？

删除：

• 通用概念解释
• 行业背景
• 重复规则
• 漂亮但不改变行为的原则
• 模型已经知道的基础最佳实践

保留：

• 触发边界
• 本地规则和 gotchas
• 禁止事项
• STOP 条件
• 输出模板
• 验证清单
• 兼容性、权限、回归约束

Step 4：检查 STOP 与失败处理

Skill 必须说明何时停止：

• 缺少必要输入时停止并说明缺失项
• 范围不匹配时停止并转交相邻 Skill
• 用户只要求评审时不得直接修改
• 涉及生产、部署、删除、发送、支付、提交等副作用时必须有明确确认或阶段门
• 规则冲突时按用户最新指令、项目入口、安全约束和 CANON 裁决
• 无法验证结果时不得声称完成

Step 5：检查输出契约和 Done When

输出契约至少包含：

## 结论
## 判断依据
## 执行结果 / 设计方案 / 评审结果
## 风险与边界
## 验收清单

Done When 必须能被验证，不得写成“看起来合理”“基本完成”。

Step 6：检查 progressive resources

• SKILL.md 放高频规则和硬门
• 辅助 .md 只放长模板、长示例、评分表、证据格式，并由主 SKILL.md 明确引用
• 重复确定性逻辑进入 scripts，而不是每次让 agent 重新推理
• 本仓库中辅助 .md 必须进入 skills-lock.json 的 auxiliaryHashes

Step 7：检查 eval 样本

至少从两个角度审查：

• Trigger Eval: should-trigger 与 should-not-trigger 都覆盖；重点覆盖 near-miss、短输入、口语输入、隐含意图
• Task Eval: 包含 expected behavior、must include、must not include、done when

没有正式 eval 文件时，也必须在审查报告中列出代表性样本和结论。

验证失败处理

常见说辞

红旗

<HARD-GATE> 以下任何一个出现，立即停止并要求修复：

• description 只解释“这个 Skill 是什么”，没有说明何时使用
• description 无法排除相邻 Skill 的 near-miss
• SKILL.md 大量解释通用概念，缺少本地规则或 gotchas
• 没有“何时不使用”或 STOP 条件
• 没有输出模板、Done When 或验证清单
• 修改技能后未同步 skills-index.json、skills-router.json 或 skills-lock.json
• 辅助 .md 未被主 SKILL.md 引用
• 机械重复逻辑没有脚本化，且已出现重复手写
• 无法验证却声称完成

</HARD-GATE>

验证清单

• Skill 类型已明确，范围窄而稳
• description 写明 should-trigger 和 near-miss 排除边界
• 低价值解释已删除或下沉到辅助文件
• 本地规则、gotchas、禁止事项和 STOP 条件清楚
• 输出契约和 Done When 可执行、可验证
• progressive disclosure 分层正确，辅助文件被主 SKILL.md 引用
• 重复确定性逻辑已脚本化或明确说明为什么不用脚本
• Trigger Eval 覆盖 should-trigger、should-not-trigger 和 near-miss
• Task Eval 覆盖 expected behavior、must include、must not include、done when
• 本仓库变更已运行 scripts/generate-index.sh、scripts/generate-router.sh、scripts/update-lock.sh <skill> 和 ./validate；新增技能时 update-lock.sh 必须自动创建 lock entry

输出模板

# Skill Quality Review — <skill-name>

## Verdict
- Status: PASS / FAIL
- Skill type: routing / design / execution / governance

## Routing
- Should trigger:
- Should not trigger:
- Near-miss risks:

## Contract Findings
| Severity | Area | Finding | Fix |
|----------|------|---------|-----|
| Blocking | Description | ... | ... |

## Eval Coverage
- Trigger eval samples:
- Task eval samples:
- Missing coverage:

## Done When
- [ ] description 路由准确
- [ ] STOP / Output Contract / Done When 齐全
- [ ] index / router / lock / validate 同步完成