Evaluating skills

Evaluating Skills

Overview

A skill is not judged by how much it documents. It is judged by whether a future agent, under real pressure, will (1) find it, (2) afford to load it, (3) actually be bound by it, and (4) be taught something true. Those are the four dimensions below. A skill can be beautifully written and still fail all four — because it reads well to you (a smart model with full context) while doing nothing for the pressured agent it's supposed to steer.

Core move: for every rating you give, quote the line that earns it and name the concrete fix. A rating without evidence is an opinion; this skill produces evidence.

When to use

• Reviewing or scoring any SKILL.md — a teammate's, a downloaded one, or your own.
• Self-checking a skill you just wrote, before shipping (this is the highest-value use).
• Diagnosing a symptom: "this skill never triggers", "the agent ignores it", "it bloats context".

Not for: grading prose quality of non-skill docs, or enforcing mechanical style that a linter/regex should own (that failure belongs in lint, not in a review — see 约束形态).

The four dimensions

维度	它回答的问题	强的样子	弱的样子
触发力 (discovery)	未来 agent 找得到、且会正确调用吗？	description 只写"何时用"、第三人称、含症状关键词	description 抄了流程摘要，或抽象到无法匹配
上下文经济 (context economy)	它尊重共享的上下文窗口吗？	主文件精简、重内容下沉 references、一层深	什么都塞进 SKILL.md、解释 agent 早就懂的东西、@ 强加载
约束形态 (form fit)	指导的"形状"匹配它要防的失败吗？	纪律失败→禁令+反诡辩表；走形失败→正向配方	对"走形/漏项"用禁令（会反噬）、机械约束写进正文
可测试性 (grounded)	它源于观察到的真实失败，还是凭空想象？	有 baseline 失败痕迹、一个真实例子	一次性叙事、想象的边界、多语言稀释、无依据的断言

深层信号目录（每维的细则、真实正反例）在 references/signals.md——评审时读它对照，不要只凭本表。

How to evaluate

1. 读全量 + 量体。完整读目标 SKILL.md，列出捆绑文件，量出体积：

   wc -l <skill>/SKILL.md; wc -w <skill>/SKILL.md
   ls -R <skill>/   # 看有没有 references/ scripts/ assets/，以及嵌套层数
   

2. 判类型 + 定"目标失败"。先判它是 discipline / technique / pattern / reference 哪一类（决定各维权重，见下）。再问：不用它时 agent 会出什么错？ 这是"约束形态"维的前提。文件若没明说，就从正文推断，并在报告里标"(推断)"——不要假装文件给了你答案。
3. 逐维定级，每条附原文证据（引用或行号）+ 具体改法。定级用 强/够用/弱：
   • 强：达标，真实使用中扛得住。
   • 够用：能用，但有一个值得修的真实弱点。
   • 弱：一个会让 skill 在实战中失效的缺陷（触发不了 / 撑爆上下文 / 约束绑不住 / 教了没验证过的东西）。
   • N/A：该维对此类型不适用（如纯 reference skill 谈不上"纪律约束"）。
4. 产出评分卡（下方固定模板）。
5. 收尾：一句话总体裁定 + 最高杠杆的 3 个修改。

类型如何影响权重：discipline skill（强制纪律的规则型，如 TDD、并发不变量、幂等约束）的命门是约束形态与可测试性；technique/reference skill 的命门是触发力与上下文经济。别用错权重去苛责——对一个纯 API reference 抱怨"没有反诡辩表"是文不对题。

各维快检

每维先记住"头号致命伤"；要细则、正反例与标杆对照时读 references/signals.md。

• 触发力：description 是否以 "Use when…" 开头、第三人称、只写何时用而不摘要流程？（头号致命伤：description 抄了工作流，agent 照 description 做就不读正文。）
• 上下文经济：SKILL.md 是否精简（常驻类 <200 词、一般 <500 行）、重引用一层深拆进 references、无 @ 强加载、不解释 agent 本就懂的常识？
• 约束形态：先分类目标失败，再验形状——纪律型给禁令+反诡辩表，走形/漏项型给正向配方或结构槽位，条件型挂可观测谓词，机械约束下沉 lint。形状↔失败的完整对照表见 signals.md §3。
• 可测试性：有没有"观察过 baseline 失败"的痕迹（针对具体诡辩而非泛谈）？例子是一个真实可跑的，还是叙事 / 多语言稀释 / 凭空想象的边界？断言有依据还是臆测？

评分（10 分制，一位小数）

数字是评级的量化投影，不能脱离评级与证据单独存在——先定 强/够用/弱，再在档内给小数。这样分数动不了评级，也就堵住了"刷分"和假精度（纯百分制的病根就在这）。

档位 → 分数区间（档内小数反映缺陷轻重）：

• 强 = 8.0–10.0（默认 8.5；无可挑剔才上 9.5+）
• 够用 = 5.0–7.9（近强给 7.x，近弱给 5.x）
• 弱 = 0–4.9（有救但当前会失效给 3–4.x；完全失效更低）
• N/A 不计入。

总分 = 按类型加权的均值（命门维 ×2，其余 ×1），四舍五入到一位小数：

类型	×2（命门）	×1
discipline	约束形态、可测试性	触发力、上下文经济
technique	触发力、上下文经济	约束形态、可测试性
pattern	触发力、约束形态	上下文经济、可测试性
reference	触发力、上下文经济	可测试性（约束形态常 N/A）

防刷分红线：任一维=弱 → 总分封顶 5.9。按定义"弱"就是实战会失效，其它维再高也救不回来。总分只是一个便于沟通的握手值，裁定与改法永远以评级+证据为准，不许倒过来"凑分数"。

评分卡模板（固定）

## Skill 评审:<name>
**类型**:discipline / technique / pattern / reference
**目标失败**:<不用它会出什么错;文件未言明则标"(推断)">

| 维度 | 评级 | 分数 | 依据(原文/行号) | 改法 |
|---|---|---|---|---|
| 触发力 | 强/够用/弱/NA | x.x | "<引用>" | <具体改法> |
| 上下文经济 | … | … | … | … |
| 约束形态 | … | … | … | … |
| 可测试性 | … | … | … | … |

**总分**:x.x / 10(<类型>加权;命门维×2;有"弱"则封顶5.9)
**总体裁定**:<一句话:能不能发 / 最先修什么>
**最高杠杆的 3 个修改**:
1. …
2. …
3. …

评审的立场（怎么判才准）

四条校准原则，套在每一次定级上——它们说的是"准确的判断长什么样"，照着做即可：

• 按"压力下的 agent"判，而非按"读起来顺不顺"判。你是满上下文的聪明模型；你觉得清楚，不代表一个赶时间的 agent 会遵守。评级回答的是"它绑不绑得住"，不是"它写得美不美"。
• 把"面面俱到"先当作拆分信号。内容越全越先问：这些该不该下沉 references？"详尽"与"臃肿"常常是同一段文字，判上下文经济时按这个默认怀疑。
• 禁令先验形状：见到禁令，先定位目标失败是纪律型还是走形/漏项型。纪律型→禁令正确；走形/漏项型→配方或结构槽位才对，此时该判"弱"并在改法里给出配方版本。
• 每一维都下一个明确判断：评审的价值在于点出会失效的缺陷。一份四维全"够用"的报告等于没评。

边界与诚实

有些维度光看文件判不准——尤其"可测试性"里"是否真观察过 baseline"，文件通常不会写。这时靠症状推断（叙事化、想象的边界、无依据断言都是"没测过"的味道），并在依据里标注"(推断)"。判不准就说判不准，不要硬给一个假装确定的评级。