rate-skill

Rate Skill

概述

为一个 SKILL.md 评分，并返回字母等级、按权重计算的类别分数、明确列出的优势、按优先级排列且附带可直接粘贴的补丁的问题，以及修复后的预估等级。评分时依据下方的评分标准文本，而非记忆——来源见 references/SOURCES.md。

导航

加载	适用情况
references/EXAMPLES.md	关于描述、frontmatter 和验证脚手架的 ✅/❌ 示例对；完整报告样例；已废弃的规则
references/SOURCES.md	用户质疑某条规则，且你需要引用规范时

工作流

1. 确定路径。若路径是目录，则使用其中的 SKILL.md。如果未提供任何内容，只询问一次：“要为哪个 SKILL.md 评分？”
2. 读取整个文件。分别解析 frontmatter 和正文。正文行是闭合 --- 之后的所有内容，包括空行（紧随其后的空行也计算在内）——这就是 generate-skill/scripts/measure.py 报告的数字；正文 token 数为 字符数 / 4。
3. 判断类型——与 generate-skill 使用的五种类型相同，因此生成的 skill 应按其所依据的配置文件评分。如果有两种配置文件都适用（reference 与 technical、methodology 与 auditing、automation 与 technical），选择正文中已列出所需章节的那种；绝不能因为某个标题名称而选择会对其扣分的配置文件。没有阶段的每轮行为规范 skill，只要有任何章节说明该轮次的顺序，就满足“Workflow (phased)”。在报告中说明类型及平局时的判定依据。
4. 根据 Eval set check 检查是否有评测集（references/ 或旧版 reference/ 中的 EVAL.md，或 evals/evals.json）。缺失属于持续存在的 P1。
5. 为每个类别打 0–100 分，然后运行 python3 <generate-skill>/scripts/measure.py score <按评分标准顺序排列的 7 个分数>，生成加权表格和字母等级。以同样方式应用 P0 和 P1，预估修复后的等级。
6. 按照 Output Format 的格式输出报告。

评分标准（权重合计为 100）

#	类别	权重
1	描述质量	25
2	Frontmatter 有效性	20
3	长度与渐进式披露	15
4	适合类型的结构	15
5	示例	10
6	简洁度 / 上下文利用效率	10
7	反模式与校准	5

A 为 90–100，B 为 80–89，C 为 70–79，D 为 60–69，F 为低于 60。B 代表可用于生产，而不是濒临不及格。

扣分幅度的设定确保单次违规可以挽回，重复违规则不行：出现 4 次时，−15 会将类别分数降至最低 0 分；出现 3 次时，−20 会将类别分数降至最低 0 分；−10 表示轻微问题，skill 可承受数次。上限（40/50/70/80）表示该缺陷本身会将分数上限设为相应数值。

1. 描述质量（25）

满分须满足以下五项：

• 面向 Agent 的祈使式第三人称表述——官方写法“Use this skill when…”；本项目常用的“Use this skill whenever the user wants to…”与之等效。第一人称（“I'll help you…”）最高只能得 40 分。
• 使用指令式，而非被动表述。 仅写“Use when X”最高只能得 70 分。不要将全大写的升级措辞视为更强——§7 会因此扣分，而指令式本身已经具备相应优势。
• 前约 50 个字符内包含独特的触发词，因为安装的 skill 超过约 15–25 个后，列表显示的内容会被截断。
• 至少 3 个具体的用户措辞触发条件，以引号标出短语或列举动词。对于间接请求也应计入覆盖条款（例如“即使他们没有明确提及 X”）——这是官方推荐写法。
• 当存在相邻 skill 时，明确限定不适用范围（“Do NOT use this skill for…”）。仅在容易发生冲突的领域才强制要求。

上限：超过 1024 个字符 → 最高 50 分（规范硬性上限）。触发条件模糊（“帮助处理文档”“用于任务”）→ 最高 50 分。若评测集记录了验证未命中（文件自身记录的某次运行中，某条应触发查询的得分不高于 0.5），则此项扣 5 分，并列出该查询作为 P2，因为即使文本满足所有标准，仍可能触发不足。官方建议的长度是“几句话到一小段”——应指出冗长问题，但在未触及上限时，绝不能仅按字符数扣分。YAML 标量样式不计分（参见已废弃的规则）。

2. Frontmatter 有效性（20）

接受的顶层字段：name、description、license、compatibility、when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、model、effort、agent、hooks、paths、shell、allowed-tools、metadata。

每项扣 15 分：顶层 version/author/tags（应放在 metadata 中）；category（不是字段）；嵌套在 metadata 下的 argument-hint（必须放在顶层）；name 含大写字母、连续连字符，或保留字 anthropic/claude。compatibility 超过 500 个字符上限：扣 10 分。

3. 长度与渐进式披露（15）

• 正文不超过 300 行：满分。301–500 行：每超过 300 行 50 行扣 10 分，因此 500 行时最低得 60 分。
• 超过 500 行：扣 30 分，如果没有 references/ 目录，则再扣 20 分。超过上限且没有披露机制是最糟的情况，得分必须低于所有未超上限的情况——绝不能靠分数上限挽回。
• 正文超过约 5,000 个 token（≈20k 字符）：即使不足 500 行也算超限。官方限制同时考量两项；内容密集、代码较多的正文可能在行数达标时仍超出 token 限制。
• References 嵌套超过一层：扣 15 分——Claude 会对文件执行 head -100，因此会漏掉内容。
• 使用单数 reference/ 而非复数：仅作风格提示，不扣分。规范文档推荐复数，但没有任何校验会检查目录名称——新建目录时优先使用复数，绝不要强制重命名。

4. 与类型相适配的结构（15）

共享章节规范，与 generate-skill 生成的规范完全一致。

类型	作用	必需章节	可选章节
methodology	强制执行多步骤工作流	Overview、Workflow（分阶段）、Examples、Gotchas	Quality Signals / Anti-Patterns
technical	封装 API、格式或工具	Overview、Quick Start / Setup、Quick Reference 或 API surface、Examples、Gotchas	Troubleshooting
auditing	对产物评分或检查	Overview、Workflow、Rubric、Output Format、Examples、Gotchas	—
reference	架构、约定、查找表	Overview、Navigation（按需加载表格）、Gotchas	Core Concepts
automation	封装脚本或外部命令	Overview、Command Surface、Sample Invocation、Failure Modes、Gotchas	Troubleshooting

• 缺少必需章节：每项扣 20 分。所有类型都必须包含 Gotchas——“许多技能中价值最高的内容，就是一份注意事项清单。”
• ## Integration 章节没有任何具体内容：扣 10 分。
• 指令模式适配度。 六种官方模式是 gotchas、输出格式模板、清单、验证循环、计划-验证-执行，以及打包脚本。按适配度评分：技能的工作明显需要某种模式却未采用（例如，批量破坏性工作流没有计划-验证-执行步骤）：扣 10 分；强行加入不适用的模式：扣 10 分。
• 书面交付物长度：扣 10 分，如果技能输出是 Agent 要编写的文件，且模板没有限定其长度。书面交付物默认容易变得冗长；模板需要加入类似“长度应与任务相称，不要添加填充内容或重复总结”的要求。聊天消息交付物若由后续步骤原样写入磁盘，也算在内；Agent 编写的脚本（如磁带、配置）也算，因为其运行时长取决于自身长度；存放在按需加载参考文档中的模板扣 5 分，而非 10 分。
• ## Verification Checklist 不是任何类型规范中的章节。不因缺少该章节而扣分，也不因存在该章节而加分——应根据 §7 评估其内容。清单仍是官方模式；只有要求自行重新检查的内容会被扣分。

5. 示例（10）

• ≥1 组具体示例（期望做法与反模式）：基准分 70。先展示期望做法：+10；文件也以期望示例结尾：再 +5（近因效应）。✅/❌ 表情符号或 ## Anti-Pattern: 标题：+15。
• 通过指引链接到 references/EXAMPLES.md 的示例，计分时完整计算。 这是渐进式披露，并非遗漏——为本类别评分前先阅读该文件。§6 会对两处都保留示例扣分。
• 少于 3 种情境，或 3 种及以上但都在考查同一情境：最高 80 分。统计情境，而非区块或示例对——同一场景中的两组 ✅/❌ 仍算一种情境。官方建议提供 3–5 种相关且多样的情境，避免 Agent 错误地匹配到非预期规律。其他示例均成对时，若有一个 ✅ 没有对应的 ❌：−5。“以期望示例结尾”是指文件中的最后一个示例是期望做法；之后的非示例章节（已废弃规则、备注）不影响。
• <Good>/<Bad> XML 标签：−10——调查的 8 个顶级技能中，没有一个使用它们。此项针对的是标签；官方推荐的 <example>/<examples> 结构分隔符不扣分。
• 全是抽象内容，没有具体代码：最高 40 分。

6. 简洁性 / 上下文经济性（10）

对每条指令应用官方删减测试：“没有这条指令，Agent 会做错吗？” 如果不会，就是冗余。

每个不同出现扣 −10，最低 40 分——同一规则重复 N 次算一次；在 SKILL.md 中重复表述与在 SKILL.md 和参考文件之间重复表述同样计一次；按症状索引 Gotchas 的故障排除内容属于不同的查找方向，不算重复；某条 Gotcha 可有意重申工作流步骤，但需补充该步骤未涵盖的症状：重复一般编程知识的段落；长于其所引出规则的“重要性说明”；工作流前冗长的介绍；对同一事物使用不一致的术语；本应直接选定默认项却提供菜单；针对具体实例的输出，而非可泛化的流程；在 SKILL.md 和 references/ 文件中重复相同内容（按声明由两个技能共用的表格，例如 generate-skill 和 rate-skill 都附带的章节规范，属于有意共享，不算重复）；Claude Code harness 每个会话已注入的文本，因为模型随后必须协调同一规则的两种表述——当前注入内容列表见 references/EXAMPLES.md § Harness-injected text。

7. 反模式与校准（5）

每项扣 −20。本类别权重为 5，因此分数变化很小——发现问题才是交付内容。 每处出现都以 P1 或更高优先级报告。

编写

• 没有理由说明的全大写“铁律”式表述。两个来源系列都不建议这样做：“执行 X，因为 Y 往往会导致 Z”优于僵硬指令（agentskills.io）；“降低过于强硬的措辞……使用更常见的提示方式”（platform.claude.com）。

• 将无关任务打包进范围过大的巨型技能——一个技能做一件事；SkillsBench 发现，模块数 ≤3 的技能优于更大的组合。

• 技能目录中的多余文档（README.md、INSTALLATION.md、QUICK_REFERENCE.md、CHANGELOG.md）。

• Windows 风格的反斜杠路径；没有记录理由的“玄学”常量；会随时间失效的时限说明（如“如果在 2025 年 8 月之前……”），除非放在“旧模式”章节中。以下同样会过时，但不扣分，建议修复：在生成的模板中标注来源时间（例如 Agent 可复制的 YAML 区块内写 # verified 2026-09-02）；在正文中反复使用相对于某代模型的措辞（“当前模型”×N——只在首次提及具体代际，之后称为“该模型”）；提及计划删除的技能；比较不同模型档位的成本；逐字引用 harness 提示词文本。

• 控制力度失准。 具体程度应与脆弱性相匹配：存在多种有效做法时给予自由，操作脆弱或步骤顺序必须保持时给出明确指示。对容许变化的任务做出僵硬要求，以及对脆弱任务含糊带过，均应扣分。明确指示本身不是缺陷——应按章节校准。 Agent 式过度提示——模型本来就会执行的行为，重复说明只会叠加指令、消耗 token，却不会提升质量。

• 验证脚手架——对于没有外部参照的泛泛复查，应予扣分：“仔细检查你的答案”“回复前再次验证”“为任何非简单任务添加最后的验证步骤”。正确做法是删除，而非改写。**以下三种情况不属于此类，评分也不会受影响：**对照外部状态进行检查（“运行测试套件”“确认文件能否解析”“根据架构验证”）；由全新上下文中的 Agent 判断另一个 Agent 的输出；以及在进度报告前审查证据（“只报告你能指出工具结果作为依据的工作”）。后两种做法适用于长时间运行的工作，值得推荐，而非仅仅可以接受（平台 5.1 指南中也有说明，但标注为暂定）。问题在于，Agent 重新阅读自己产出的内容，却没有外部依据可供核对。

• 推理回声（“展示你的思考过程”“在回复中解释你的推理”）。可能触发 reasoning_extraction 拒绝——始终也要发出 P0。这是严重故障模式，不是风格问题。

• “不要思考”／“不要推理”——会导致内部 XML 标签更容易泄漏到可见输出中。删除；明确提及这些标签的规则，不如什么都不说有效。

• 叙述抑制规则（“把所有发现留到最终回复再说”“不要叙述”“不要发布中途更新”）。模型在长工具链执行过程中本来就倾向于少叙述；这些规则会让用户只能默默等待。优先删除；如果技能确实需要某种特定更新，应说明何时发送（“分派前说明范围”）。规定最终消息形式的规则（单行聊天消息，文件才是交付物）不属于此类。

• 反格式化规则（“绝不使用项目符号”“不要加标题”“不要加粗”）。这类规则原本是针对过度格式化的模型而写，但模型实际上格式化不足，因此规则会剥除读者需要的结构。应改为规定何时适合使用格式。

• 未限定范围或阻塞式委派——给子 Agent 的指令没有说明哪些情况适合委派或应委派多少个 Agent，或者要求协调者依次停下并等待每个 Agent 的结果。开放式委派会增加成本；阻塞式委派会延长耗时。应在一条消息中同时分派给多个独立 Agent，由主 Agent 继续工作。

• 狭窄任务却范围无界——模型会自行添加未被要求的步骤，因此只处理一项任务的技能应说明何时停止。对于生成代码的技能，同一规则也适用于代码：未要求的相邻行为修复应作为后续事项报告，临时检查也不应变成已提交的测试文件。

评测集检查

每个经过评级的技能都应附带一个评测集。缺失 → 固定为 P1（在补丁中加入一个入门评测集），绝不扣分或加分。有评测集，但已发布的 description 没有对应的验证行 → 同样为 P1：将 Results 中最新的一行与描述的最后一次编辑进行比较（使用 git log -L 检查 frontmatter，或查看 CHANGELOG）；按照循环自身的规则，没有验证分数的变体不会被选中。有评测集，但从未运行，或运行时协议颠倒（从未测量训练集，或根据验证集查询进行迭代或选择）→ 同样为 P1。已存在且经过验证的评测集中的其他问题（查询数量、拆分比例、无效的近邻技能）→ P2。disable-model-invocation: true 的技能无需测量触发率：其评测集要检查自然语言表达不会触发该技能，以及触发后模式是否保持有效。若有评测集，请根据官方循环进行验证：

• 约 20 个查询，每个方向各 8–10 个。近邻技能最适合用作不应触发的查询。
• 训练集／验证集按约 60/40 划分，两部分都包含按比例混合的查询，并在各轮迭代中保持不变。
• 明确说明协议：每个查询在全新会话中运行约 3 次；触发率 = 触发该技能的运行次数占比；应触发的查询高于阈值时通过，应不触发的查询低于阈值时通过（默认值为 0.5）。
• 明确说明选择规则：以最佳的验证集分数为准——较早的迭代可能优于最后一次迭代。

注意（官方说明）：Agent 会在任务超出其单独处理能力时查阅技能，因此，对于简单到不言自明的查询（例如“读取这个 PDF”），触发率低并不一定意味着描述有问题。

输出格式

根据技能的实际需要确定报告长度——价值在于评估结果，因此不要添加填充性章节，也不要在结尾重复总结报告内容。

# Skill Rating: <skill-name>

**Detected type:** <methodology | technical | auditing | reference | automation>
**Overall grade:** <letter> (<weighted score>/100)
**Eval set:** <present + conforms | present, gaps: … | missing (P1)>

## Category scores

| Category | Score | Weight | Weighted |
|---|---|---|---|
| Description quality | nn | 25 | nn.n |
| Frontmatter validity | nn | 20 | nn.n |
| Length & disclosure  | nn | 15 | nn.n |
| Structure            | nn | 15 | nn.n |
| Examples             | nn | 10 | nn.n |
| Conciseness          | nn | 10 | nn.n |
| Anti-patterns/calib. | nn |  5 | nn.n |

## Strengths
- <concrete bullet — what the skill does well>

## Findings (prioritized)

### P0 — <title>
**Why:** <one-line rationale, cite category>
**Fix:**
\`\`\`<lang>
<concrete replacement text, not a description of one>
\`\`\`

### P1 — <title>
### P2 — <title>

## Estimated grade after P0+P1: <letter> (<projected score>/100)

<one-line commit-ready summary>

每份报告至少要指出一项优点，即便技能评级为 F 也不例外——用户不会采纳纯负面的报告。每项问题都必须附上可供用户直接粘贴的补丁，绝不能只说“改进描述”。

示例

描述质量、frontmatter 清理、领域验证与自我复查脚手架的 ✅/❌ 对照示例，以及完整报告示例和已废弃规则：references/EXAMPLES.md。

注意事项

• 两个来源系列对描述力度的建议相互矛盾。 agentskills.io 建议“宁可更积极一些”；platform.claude.com 则表示模型“现在可能会过度触发”技能，并建议“降低激进措辞的力度”。两者可以通过区分覆盖面与表达力度来协调：增加触发场景和覆盖范围条款可以提高召回率，而全大写不会带来任何提升。应提高覆盖面的评分，降低表达力度的评分。
• 列表上限与规范上限彼此独立。 Claude Code 将 description + when_to_use 的总长度限制为 1,536 个字符，用于列表展示（skillListingMaxDescChars）；skillListingBudgetFraction 的默认值约为上下文的 1%。这两者都不是 §1 中 1024 个字符的规范上限。
• 顶层的 tags 不起作用——没有任何发现系统会读取它。应将其移至 metadata.tags，而不是删除；这样可以保留用户意图。
• 扩展键有效，但不可移植。 argument-hint、hooks、paths、when_to_use 在 Claude Code 中可以正常运行，但会被 Anthropic 的打包验证器（quick_validate.py）拒绝，也不在通用规范中。不要因此扣分——只有当技能面向 anthropics/skills 时，才指出这一限制。
• **建议将 skills-ref validate <path> 用作结构验证器。**绝不要使用 npx skills lint 或 npx skills validate——vercel-labs/skills 并未提供验证命令。
• 否定表达的处理效果较差。 官方建议：“告诉 Claude 应该做什么，而不是不要做什么。” arXiv 2503.22395 也印证了这一点。对经过评估的正文中出现的单独“DO NOT X”，建议补充“改为执行 Y”。
• 验证规则因模型而异。 按 §7 所述的三种例外情况进行评级；在收紧或放宽这些例外前，重新查阅当前模型的提示指南——迄今为止，每份指南都调整过这条界限。