skill-evaluation

Skill 评估

如果你需要了解轴 1、3 和 4 背后的词汇和测试（包括开头词、完成标准、上下文指针、删除测试和失败模式定义），请在为这些轴评分前阅读 references/mechanics.md。

来源

• 构建 Claude Code 的经验：我们如何使用技能 — Anthropic，2026 年 6 月
• “缺失的手册：如何编写优秀的技能”——Matt Pocock，AI Engineer World's Fair 2026（视频），以及他的 writing-great-skills 技能

参数

参数	描述	默认值
target	要评估的技能目录或 SKILL.md 的路径	询问用户
output	评分卡的写入路径	<target>/EVALUATION.md
compare	可选的第二个技能，用于并排比较	无

也可无人值守运行：在 CI 中，将 target 指向 PR 中发生更改的技能，并使用 scripts/score.py --fail-below 60 ... 设为门禁——低于阈值时会以非零状态码退出，导致检查失败。

评估标准

共 18 项标准：14 项核心标准，对每个技能评分；另有 4 项条件标准，仅在技能所属类别适用时评分——否则标记为 N/A，并从加权平均分的分子和分母中排除。每项评分为 0–100，并附上引用文件、章节或行号的证据。

轴 1 — 触发（调用）

#	评估标准	权重	关键问题
1	调用方式设计	2x	由模型调用还是由用户调用，是否经过审慎选择且适合此技能？由模型调用需付出上下文负担（每轮都会加载描述）；由用户调用需付出认知负担（人类负责查找）。只会由用户手动触发的技能应设为由用户调用。
2	描述质量	2x	由模型调用：开头词是否置于前面，每个分支是否只有一个触发条件（用同义词重命名同一分支属于重复），是否避免了与正文内容重复的身份描述。由用户调用（disable-model-invocation: true）：是否使用面向人的单句描述，且没有触发词列表。根据技能实际使用的模式评分——切勿因由用户调用的技能缺少触发短语而扣分。

轴 2 — 结构

#	评估标准	权重	关键问题
3	步骤与参考资料的清晰度	1x	技能是否区分了有序步骤和按需参考资料？全部为参考资料或全部为步骤的技能都有效——应评估清晰度，而非两者的比例。相关材料是否放在一起（定义、规则、注意事项是否归在同一标题下）？
4	分支感知式信息披露与指针	2x	每个分支都需要的材料是否直接写在正文中，只有部分分支需要的材料是否通过上下文指针引用？每个指针的措辞是否说明何时应跟随它（“如果需要 X，请阅读 Y”）？指向必备材料的指针若措辞不明确，会造成差异问题。
5	简洁（避免冗长）	2x	SKILL.md 是否精简——最多 500 行，越短越好——且每一行都值得其上下文开销？
6	范围连贯	1x	技能是否专注于一件事，并能与其他技能组合使用，而不是涵盖过多内容？

轴 3 — 引导

#	标准	权重	核心问题
7	关键词	2x	该 skill 是否使用简洁、优先级高的术语（“vertical slice”“tight”“red”）来锚定行为，并始终如一地重复使用？是否可以将冗长的段落浓缩为一句？
8	完成标准与执行工作	2x	对于包含步骤的 skill：每个步骤是否都以可检查且全面的完成标准收尾？含糊的标准会导致过早完成。对于纯参考类 skill：是否对参考内容本身设定了全面性要求（“应用每条规则”）？如果两者均不适用，标为 N/A。
9	注意事项章节	2x	是否明确记录了失败点、边缘情况和易踩的陷阱？
10	以专业经验为基础	2x	内容是否源于观察到的失败和真实项目事实，而非泛泛的“最佳实践”？
11	避免强行规定	1x	skill 是否留有调整空间——采用流程而非宣告、提供默认值而非菜单，同时避免规定过多？

轴 4 — 精简

#	标准	权重	核心问题
12	无效内容（删除测试）	2x	逐句执行删除测试：如果删掉某句话后行为不变，那么这句话就是无效内容——包括重复陈述模型默认就会执行的行为。请为候选句标注行号。
13	单一事实来源	1x	每个含义是否只出现在一个地方？SKILL.md 与 references/ 之间的重复也要计入。
14	相关性与沉积	1x	是否存在过时语句、累积叠加的内容，或已不再影响 skill 行为的材料？

条件性标准

仅当 skill 所属类别（来自 references/categories.md）适用时才评分；否则标为 N/A，并在加权平均中完全排除。

#	标准	权重	适用类别
15	设置流程	1x	library-and-api-reference、data-fetching-and-analysis、ci-cd-and-deployment、infrastructure-operations
16	记忆机制	1x	business-process-automation、data-fetching-and-analysis、runbooks
17	脚本与库	1x	product-verification、code-scaffolding-and-templates、code-quality-and-review、data-fetching-and-analysis、infrastructure-operations
18	按需钩子	1x	code-quality-and-review、ci-cd-and-deployment

可根据判断在任一方向调整此表：当某个 skill 明显能从某项标准中获益时，即使它不属于表中类别，也应对该标准评分（例如，某个非 product-verification skill 显然需要辅助脚本）；而即使 skill 属于适用类别，如果该模式不适合其形态，也应标为 N/A（例如，归入 code-quality-and-review 的纯参考类词汇 skill 没有可由钩子执行的内容）。无论哪种情况，都要在评分卡中说明调整理由。

总分

overall = sum(score × weight) / sum(weight)

N/A 标准不计入任何一项总和——绝不能按 0 分处理，也不计入权重。

评分指南

分数	含义
0	完全不存在
1–25	投入极少，仅停留在表面，几乎未涉及该标准
26–50	有所涉及，但存在明显缺口
51–75	实施扎实，仍有改进空间
76–90	实施良好，仅有少量缺口
91–100	堪称典范——可作为他人的参考

等级标准

等级	范围	含义
A	80–100	达到生产质量，可作为参考的 skill
B	60–79	良好的 skill，只需少量改进
C	40–59	功能可用，但存在明显缺口
D	20–39	需要大幅返工
F	0–19	仅有框架，尚未达到生产就绪状态

工作流

1. 阅读目标技能 — SKILL.md、其前置元数据（检查是否有 disable-model-invocation），以及技能目录中的每个文件。

2. 阅读 references/mechanics.md — 词汇，以及 Axes 1、3 和 4 所依赖的测试，包括上下文指针的措辞如何才算有效。

3. 分类 — 使用 references/categories.md 及其决策树分配类别。类别决定适用哪些条件标准。

4. 为所有适用标准评分 — 引用或剔除：只有在评分依据引用了具体证据（文件、章节或行）后，才能为标准评分；没有引用，就不评分。若条件表或你自己的判断认为某项标准不适用，则标记为 N/A。完成条件：每项适用标准都有分数和引用，每项 N/A 都有原因。

5. 触发评估 — 实证测试技能描述是否确实会触发调用。完整机制见下方的 触发评估 部分。对用户调用的技能（disable-model-invocation: true）跳过此步骤 — 这类技能没有可供测试的描述。

6. 诊断失效模式 — 完成条件：对照下表检查每种模式，并为其提供引用（文件:行），或说明不适用。

7. 评估加分模式 — 沿用 v1 的 4 项，加上第 5 项：

   加分项	适用条件	检查内容
   验证循环	技能会生成输出或修改状态	指示 Agent 在最终定稿前进行自检
   输出模板	技能会生成结构化输出	包含预期格式的具体模板/示例
   重流程而非重声明	技能传授方法	教授如何处理问题，而不是某个案例要产出什么
   给出默认选项而非菜单	技能提供工具/方法选择	选择明确的默认项，并简要提及替代方案
   可追踪核验的引导语	技能使用引导性词语	引导性词语足够独特，用户可以在 Agent 的推理轨迹中搜索并确认技能确实生效

   每项标记为“存在 / 不存在 / 不适用”。

8. 计算加权分数 — 使用每项标准对应的一个 criterion:score:weight 三元组运行 scripts/score.py（用分数 NA 排除该项）；脚本会输出两个总和、总分和等级。不要手动计算。

9. 将评分卡写入输出路径 — 先阅读 references/output-template.md（其中也包含设置 compare 时使用的对比模式模板），然后严格按该结构输出。

触发评估

实证测试技能描述是否会在应该调用时促使模型调用技能，并在不应该调用时让模型忽略它。这不是通过/不通过的门槛；它会生成观察数据，供评分卡使用，并为失效模式诊断提供参考。

何时运行

• 仅针对模型调用的技能。用户调用的技能（disable-model-invocation: true）没有可供测试的描述 — 跳过并将此部分标记为 N/A。

生成提示词

根据技能的描述、范围和注意事项生成 10 个提示词：

• 5 个应该触发 — 符合技能所述范围的真实用户请求。变换措辞：有些使用技能中的词汇，另一些用朴素/间接的语言描述相同需求。
• 5 个不应该触发 — 与技能领域相邻但明确超出范围的请求（例如，属于相关技能范围的任务、描述明确排除的任务，或模型无需技能即可处理的通用请求）。

每个提示词都应像真实用户会输入的内容 — 不要提及技能，也不要给出提示。

子代理执行

在独立的子代理会话中运行每个提示词，并提供目标技能。 子代理会收到一条追加到其系统上下文中的额外指令：

At the end of your response, output exactly one line in this format:
SKILLS_USED: <comma-separated list of skill names you loaded during this task, or "none">

这条指令是通用的——不会提及正在测试的技能，也不会暗示应触发什么。子代理会正常运行；它只根据提示词决定是否加载该技能。

检测

解析每个子代理响应中的 SKILLS_USED: 行。按提示词记录：

字段	值
提示词	测试提示词文本
预期	应触发 / 不应触发
已触发	是 / 否（列表中是否包含目标技能名称？）
其他技能	触发的其他技能

报告内容

报告原始计数——不作通过／失败判断：

• 应触发命中率——已触发 X/5 次
• 不应触发误触率——已触发 X/5 次（越低越好）
• 观察到的其他技能——在相同提示词下触发了哪些同类技能

这些数据为标准 #1（调用设计）和 #2（描述质量）提供实证依据，也可能揭示过度触发或描述薄弱等失效模式。

实用说明

• 如果评估环境无法启动子代理（例如，CI 环境没有 Agent 访问权限），跳过触发评估，并在评分卡中注明“trigger eval: skipped (no agent access)”。
• 鉴于评估仅用于观察而不设门槛，每个提示词进行一次试验即可。只有结果不明确时才进行多次试验。
• 在评分卡输出中保留提示词，以便技能作者将其用作回归测试集。

失效模式诊断

指出失效模式，引用证据，并提出防护措施。每种模式的防护措施在 references/mechanics.md §5 中定义一次——请据此提出。这将取代笼统的“优先改进项”列表。

模式	需查找的证据
过早完成	完成标准含糊，且仍能看到待执行步骤
引导不足	存在指令，但 Agent 未能可靠遵循
重复	相同含义出现在 2 处或更多位置，包括 SKILL.md 与参考资料之间
沉积	过时的层级、旧版参考资料、无效指令
臃肿	没有重复或沉积内容，篇幅仍然很长
无效项	不会改变模型默认行为的行
步骤埋没	内联参考内容过于繁重，掩盖了步骤

表格之后，撰写一个 优先行动项 部分：列出 3–5 项影响最大的行动，这些行动应直接从检测到的失效模式中得出，并各自引用证据。

注意：上下文过载——同一环境中过多由模型调用的技能相互争夺注意力——属于组合层面的问题，不在单项技能评估范围内。若描述的上下文负载成本值得注意，请予以记录；不要对技能组合评分。

注意事项

• 微型技能（不足约 50 行）会导致评分卡中出现大量不适用项——对实际存在的内容评分即可；规模小而精的技能也可以在少数标准上获得 A 级。
• 自我评估偏差：如果受评技能是你（或本会话）编写的，请格外严格地应用删除测试——你可能会倾向于认为自己的每一行都有意义。
• 刚重写的内容仍可能存在重复：沉积需要时间才会形成，但重复问题从第一天起就可能存在。即使是全新的技能，也要执行精简检查。

质量检查清单

交付前的最终关卡——每一项只复核相应步骤是否已完成，不增加新要求：

• 所有内容均遵循“引用或删除”原则（步骤 4）
• 所有不适用项均有说明（步骤 4）
• 已运行触发评估，或说明跳过原因（步骤 5）
• 每种失效模式均有证据支持或已排除（步骤 6）
• 已评估 5 种额外模式（步骤 7）
• 使用 scripts/score.py 计算分数，而非手动计算（步骤 8）