SKILL.md
只读
名称
skill-judge
描述
根据官方规范与最佳实践评估Agent技能设计质量。用于审查、审计或改进SKILL.md文件及技能包。提供多维度评分与可操作的改进建议。
Skill Judge
根据官方规范及从17+官方示例中提炼的模式评估Agent技能。
核心理念
什么是技能？
技能不是教程。技能是一种知识外化机制。
传统AI知识锁定在模型参数中。要教授新能力：
传统方式：收集数据 → GPU集群 → 训练 → 部署新版本
成本：$10,000 - $1,000,000+
时间：数周到数月
技能改变了这一点：
技能：编辑SKILL.md → 保存 → 下次调用生效
成本：$0
时间：即时
这是从“训练AI”到“教育AI”的范式转变——就像一个无需训练的热插拔LoRA适配器。你用自然语言编辑一个Markdown文件，模型的行为就会改变。
核心公式
好技能 = 专家独有知识 − Claude已知内容
技能的价值由其知识增量衡量——即它提供的内容与模型已知内容之间的差距。
- 专家独有知识：决策树、权衡、边缘案例、反模式、领域特定思维框架——需要多年经验积累的东西
- Claude已知内容：基本概念、标准库用法、常见编程模式、通用最佳实践
当技能解释“什么是PDF”或“如何写for循环”时，它是在压缩Claude已知的知识。这是令牌浪费——上下文窗口是与系统提示、对话历史、其他技能和用户请求共享的公共资源。
工具 vs 技能
| 概念 | 本质 | 功能 | 示例 |
|---|---|---|---|
| 工具 | 模型能做什么 | 执行动作 | bash, read_file, write_file, WebSearch |
| 技能 | 模型知道如何做 | 指导决策 | PDF处理, MCP构建, 前端设计 |
工具定义能力边界——没有bash工具，模型无法执行命令。
技能注入知识——没有前端设计技能，模型生成通用UI。
等式：
通用Agent + 优秀技能 = 领域专家Agent
同一个Claude模型，加载不同技能，成为不同专家。
技能中的三种知识类型
评估时，将每个部分分类：
| 类型 | 定义 | 处理方式 |
|---|---|---|
| 专家 | Claude确实不知道 | 必须保留——这是技能的价值 |
| 激活 | Claude知道但可能想不到 | 如果简短则保留——作为提醒 |
| 冗余 | Claude肯定知道 | 应删除——浪费令牌 |
技能设计的艺术在于最大化专家内容，谨慎使用激活内容，并彻底消除冗余内容。
评估维度（共120分）
D1：知识增量（20分）——核心维度
最重要的维度。技能是否增加了真正的专家知识？
| 分数 | 标准 |
|---|---|
| 0-5 | 解释Claude已知的基础知识（什么是X，如何写代码，标准库教程） |
| 6-10 | 混合：一些专家知识被明显内容稀释 |
| 11-15 | 主要是专家知识，冗余极少 |
| 16-20 | 纯知识增量——每个段落都值得其令牌 |
危险信号（直接≤5分）：
- “什么是[基本概念]”部分
- 标准操作的分步教程
- 解释如何使用常见库
- 通用最佳实践（“写干净代码”、“处理错误”）
- 行业标准术语的定义
积极信号（高知识增量的指标）：
- 非显而易见选择的决策树（“当X失败时，尝试Y，因为Z”）
- 只有专家才知道的权衡（“A更快，但B处理边缘情况C”）
- 来自真实世界经验的边缘案例
- “绝不要做X，因为[非显而易见的原因]”
- 领域特定思维框架
评估问题：
- 对每个部分，问：“Claude已经知道这个吗？”
- 如果解释某事，问：“这是向Claude解释还是为Claude解释？”
- 统计专家 vs 激活 vs 冗余的段落数
D2：思维模式 + 适当流程（15分）
技能是否传递了专家的思维模式以及必要的领域特定流程？
专家与新手之间的区别不在于“知道如何操作”——而在于“如何思考问题”。但当Claude缺乏领域特定的程序性知识时，仅靠思维模式是不够的。
关键区别：
| 类型 | 示例 | 价值 |
|---|---|---|
| 思维模式 | “设计之前，问自己：什么让这个令人难忘？” | 高——塑造决策 |
| 领域特定流程 | “OOXML工作流：解包 → 编辑XML → 验证 → 打包” | 高——Claude可能不知道 |
| 通用流程 | “步骤1：打开文件，步骤2：编辑，步骤3：保存” | 低——Claude已知 |
| 分数 | 标准 |
|---|---|
| 0-3 | 只有Claude已知的通用流程 |
| 4-7 | 有领域流程但缺乏思维框架 |
| 8-11 | 良好平衡：思维模式 + 领域特定工作流 |
| 12-15 | 专家级：塑造思维并提供Claude不知道的流程 |
什么算有价值的流程：
- Claude未训练过的工作流（新工具、专有系统）
- 非显而易见的正确顺序（例如，“先验证再打包，而不是之后”）
- 容易遗漏的关键步骤（例如，“编辑后必须重新计算公式”）
- 领域特定序列（例如，MCP服务器的4阶段开发过程）
什么算冗余流程：
- 通用文件操作（打开、读取、写入、保存）
- 标准编程模式（循环、条件、错误处理）
- 文档完善的常见库用法
专家思维模式示例：
在[动作]之前，问自己：
- **目的**：这解决了什么问题？谁使用它？
- **约束**：隐藏需求是什么？
- **差异化**：什么让这个解决方案令人难忘？
有价值的领域流程示例：
### 修订工作流（Claude不知道这个顺序）
1. 转换为markdown：`pandoc --track-changes=all`
2. 将文本映射到XML：在document.xml中grep文本
3. 以3-10个为一批实现更改
4. 打包并验证：检查所有更改是否已应用
冗余的通用流程示例：
步骤1：打开文件
步骤2：找到部分
步骤3：进行更改
步骤4：保存并测试
测试：
- 它是否告诉Claude思考什么？（思维模式）
- 它是否告诉Claude如何做它不知道的事情？（领域流程）
好的技能在需要时提供两者。
D3：反模式质量（15分）
技能是否有有效的“绝不要”列表？
为什么这很重要：专家知识的一半是知道不该做什么。高级设计师看到白色背景上的紫色渐变会本能地皱眉——“太AI生成的了”。这种“绝对不该做什么”的直觉来自于踩过无数地雷。
Claude没有踩过这些地雷。它不知道Inter字体被过度使用，不知道紫色渐变是AI生成内容的标志。好的技能必须明确说明这些“绝对禁止”。
| 分数 | 标准 |
|---|---|
| 0-3 | 未提及反模式 |
| 4-7 | 通用警告（“避免错误”、“小心”、“考虑边缘情况”） |
| 8-11 | 具体的“绝不要”列表，附带一些理由 |
| 12-15 | 专家级反模式，包含原因——只有经验才能教会的东西 |
专家级反模式（具体 + 原因）：
绝不要使用通用的AI生成美学，例如：
- 过度使用的字体族（Inter, Roboto, Arial）
- 陈词滥调的色彩方案（特别是白色背景上的紫色渐变）
- 可预测的布局和组件模式
- 所有元素上的默认圆角
弱反模式（模糊，无理由）：
避免犯错。
小心处理边缘情况。
不要写烂代码。
测试：专家看到反模式列表会说“是的，我通过艰难的方式学到了这个”吗？还是说“这对每个人都是显而易见的”？
D4：规范合规性——尤其是描述（15分）
技能是否遵循官方格式要求？特别关注描述质量。
| 分数 | 标准 |
|---|---|
| 0-5 | 缺少frontmatter或格式无效 |
| 6-10 | 有frontmatter但描述模糊或不完整 |
| 11-13 | 有效的frontmatter，描述有“做什么”但“何时用”较弱 |
| 14-15 | 完美：全面描述，包含“做什么”、“何时用”和触发关键词 |
Frontmatter要求：
name：小写，仅字母数字+连字符，≤64字符description：最关键字段——决定技能是否被使用
为什么描述是最重要的字段：
┌─────────────────────────────────────────────────────────────────────┐
│ 技能激活流程 │
│ │
│ 用户请求 → Agent看到所有技能描述 → 决定激活哪些 │
│ （仅描述，而非正文） │
│ │
│ 如果描述不匹配 → 技能永远不会被加载 │
│ 如果描述模糊 → 技能可能在该触发时不触发 │
│ 如果描述缺少关键词 → 技能对Agent不可见 │
└─────────────────────────────────────────────────────────────────────┘
残酷的事实：内容完美但描述糟糕的技能是无用的——它永远不会被激活。描述是告诉Agent“在这些情况下使用我”的唯一机会。
描述必须回答三个问题：
- 做什么：这个技能做什么？（功能）
- 何时用：在什么情况下应该使用它？（触发场景）
- 关键词：哪些术语应触发此技能？（可搜索术语）
优秀描述（三个要素齐全）：
description: "全面的文档创建、编辑和分析，支持
修订、评论、格式保留和文本提取。
当Claude需要处理专业文档（.docx文件）时，用于：
(1) 创建新文档，(2) 修改或编辑内容，
(3) 处理修订，(4) 添加评论，或任何其他文档任务"
分析：
- 做什么：创建、编辑、分析、修订、评论
- 何时用：“当Claude需要处理...时，用于：(1)... (2)... (3)...”
- 关键词：.docx文件、修订、专业文档
糟糕描述（缺少要素）：
description: "处理文档相关功能"
问题：
- 做什么：模糊（“文档相关功能”——具体是什么？）
- 何时用：缺失（Agent何时应该使用？）
- 关键词：缺失（没有“.docx”，没有具体场景）
另一个糟糕示例：
description: "一个用于各种任务的有用技能"
这毫无用处——Agent不知道何时激活它。
描述质量检查清单：
- [ ] 列出具体能力（不仅仅是“帮助做X”）
- [ ] 包含明确的触发场景（“当...时使用”、“当用户要求...”）
- [ ] 包含可搜索关键词（文件扩展名、领域术语、动作动词）
- [ ] 足够具体，让Agent确切知道何时使用
- [ ] 包含必须使用此技能的场景（不仅仅是“可以使用”）
D5：渐进式披露（15分）
技能是否实现了适当的内容分层？
技能加载有三个层次：
第1层：元数据（始终在内存中）
仅name + description
每个技能约100令牌
第2层：SKILL.md正文（触发后加载）
详细指南、代码示例、决策树
理想：< 500行
第3层：资源（按需加载）
scripts/, references/, assets/
无限制
| 分数 | 标准 |
|---|---|
| 0-5 | 所有内容都塞在SKILL.md中（>500行，无结构） |
| 6-10 | 有引用但何时加载不明确 |
| 11-13 | 良好的分层，存在强制触发条件 |
| 14-15 | 完美：决策树 + 明确触发条件 + “不要加载”指导 |
对于有引用目录的技能，检查加载触发质量：
| 触发质量 | 特征 |
|---|---|
| 差 | 引用列在末尾，无加载指导 |
| 一般 | 有一些触发条件但未嵌入工作流 |
| 好 | 工作流步骤中的强制触发条件 |
| 优秀 | 场景检测 + 条件触发 + “不要加载” |
加载问题：
加载太少 ◄─────────────────────────────────► 加载太多
- 引用闲置不用 - 浪费上下文空间
- Agent不知道何时加载 - 无关信息稀释关键内容
- 知识存在但从未访问 - 不必要的令牌开销
好的加载触发（嵌入工作流）：
### 创建新文档
**强制 - 读取整个文件**：在继续之前，你必须从头到尾完整读取
[`docx-js.md`](docx-js.md)（约500行）。
**绝不要在此文件上设置任何范围限制。**
**不要加载**此任务的`ooxml.md`或`redlining.md`。
差的加载触发（仅列出）：
## 引用
- docx-js.md - 用于创建文档
- ooxml.md - 用于编辑
- redlining.md - 用于跟踪更改
对于简单技能（无引用，<100行）：根据简洁性和自包含性评分。
D6：自由度校准（15分）
具体程度是否与任务的脆弱性相匹配？
不同任务需要不同级别的约束。这是关于将自由度与脆弱性匹配。
| 分数 | 标准 |
|---|---|
| 0-5 | 严重不匹配（创意任务用死板脚本，脆弱操作用模糊指导） |
| 6-10 | 部分适当，存在一些不匹配 |
| 11-13 | 大多数场景校准良好 |
| 14-15 | 全程完美的自由度校准 |
自由度谱：
| 任务类型 | 应有 | 原因 | 示例技能 |
|---|---|---|---|
| 创意/设计 | 高自由度 | 多种有效方法，差异化是价值 | frontend-design |
| 代码审查 | 中自由度 | 原则存在但需要判断 | code-review |
| 文件格式操作 | 低自由度 | 一个错误字节损坏文件，一致性至关重要 | docx, xlsx, pdf |
高自由度（基于文本的指令）：
坚持大胆的美学方向。选择一个极端：极简主义、
极繁混乱、复古未来、有机自然...
中自由度（伪代码或参数化）：
审查优先级：
1. 安全漏洞（必须修复）
2. 逻辑错误（必须修复）
3. 性能问题（应该修复）
4. 可维护性（可选）
低自由度（具体脚本，精确步骤）：
**强制**：使用`scripts/create-doc.py`中的确切脚本
参数：--title "X" --author "Y"
不要修改脚本。
测试：问“如果Agent犯错，后果是什么？”
- 高后果 → 低自由度
- 低后果 → 高自由度
D7：模式识别（10分）
技能是否遵循已建立的官方模式？
通过分析17个官方技能，我们识别出5种主要设计模式：
| 模式 | 约行数 | 关键特征 | 示例 | 何时使用 |
|---|---|---|---|---|
| 思维模式 | ~50 | 思维 > 技术，强“绝不要”列表，高自由度 | frontend-design | 需要品味的创意任务 |
| 导航 | ~30 | 最小SKILL.md，路由到子文件 | internal-comms | 多个不同场景 |
| 理念 | ~150 | 两步：理念 → 表达，强调工艺 | canvas-design | 需要原创性的艺术/创作 |
| 流程 | ~200 | 分阶段工作流，检查点，中自由度 | mcp-builder | 复杂的多步骤项目 |
| 工具 | ~300 | 决策树，代码示例，低自由度 | docx, pdf, xlsx | 特定格式的精确操作 |
| 分数 | 标准 |
|---|---|
| 0-3 | 无识别模式，结构混乱 |
| 4-6 | 部分遵循模式但有显著偏差 |
| 7-8 | 清晰模式，有微小偏差 |
| 9-10 | 恰当模式的精湛应用 |
模式选择指南：
| 任务特征 | 推荐模式 |
|---|---|
| 需要品味和创造力 | 思维模式（~50行） |
| 需要原创性和工艺质量 | 理念模式（~150行） |
| 有多个不同的子场景 | 导航模式（~30行） |
| 复杂的多步骤项目 | 流程模式（~200行） |
| 特定格式的精确操作 | 工具模式（~300行） |
D8：实用可用性（15分）
Agent能否有效使用此技能？
| 分数 | 标准 |
|---|---|
| 0-5 | 令人困惑、不完整、矛盾或未经测试的指导 |
| 6-10 | 可用但有明显差距 |
| 11-13 | 常见情况的清晰指导 |
| 14-15 | 全面覆盖，包括边缘情况和错误处理 |
检查项：
- 决策树：对于多路径场景，是否有清晰的路径选择指导？
- 代码示例：它们是否实际有效？还是伪代码会出错？
- 错误处理：如果主要方法失败怎么办？是否提供了备用方案？
- 边缘情况：是否涵盖了不寻常但现实的场景？
- 可操作性：Agent能否立即行动，还是需要自己弄清楚？
好的可用性（决策树 + 备用方案）：
| 任务 | 主要工具 | 备用方案 | 何时使用备用方案 |
|------|-------------|----------|----------------------|
| 读取文本 | pdftotext | PyMuPDF | 需要布局信息 |
| 提取表格 | camelot-py | tabula-py | camelot失败 |
**常见问题**：
- 扫描PDF：pdftotext返回空白 → 先使用OCR
- 加密PDF：权限错误 → 使用PyMuPDF并带密码
差的可用性（模糊）：
使用适当的工具进行PDF处理。
正确处理错误。
考虑边缘情况。
评估时绝不要做
- 绝不要仅仅因为看起来专业或格式良好就给高分
- 绝不要忽略令牌浪费——每个冗余段落都应导致扣分
- 绝不要被长度打动——43行的技能可以胜过500行的技能
- 绝不要跳过在脑中测试决策树——它们是否真的导向正确选择？
- 绝不要以“但它提供了有用的上下文”为由原谅解释基础知识
- 绝不要忽视缺少反模式——如果没有“绝不要”列表，那是一个重大缺陷
- 绝不要假设所有流程都有价值——区分领域特定和通用
- 绝不要低估描述字段——糟糕的描述 = 技能永远不会被使用
- 绝不要只在正文中放“何时使用”信息——Agent在加载前只看到描述
评估协议
步骤1：第一遍——知识增量扫描
完整阅读SKILL.md，对每个部分问：
“Claude已经知道这个吗？”
将每个部分标记为：
- [E] 专家：Claude确实不知道——增值
- [A] 激活：Claude知道但简短提醒有用——可接受
- [R] 冗余：Claude肯定知道——应删除
计算粗略比例：E:A:R
- 好技能：>70%专家，<20%激活，<10%冗余
- 一般技能：40-70%专家，高激活
- 差技能：<40%专家，高冗余
步骤2：结构分析
[ ] 检查frontmatter有效性
[ ] 统计SKILL.md总行数
[ ] 列出所有引用文件及其大小
[ ] 识别技能遵循的模式
[ ] 检查加载触发（如果存在引用）
步骤3：每个维度评分
对于8个维度中的每一个：
- 找到具体证据（引用相关行）
- 分配分数并附上一行理由
- 如果分数低于最大值，注明具体改进
步骤4：计算总分与等级
总分 = D1 + D2 + D3 + D4 + D5 + D6 + D7 + D8
满分 = 120分
等级量表（基于百分比）：
| 等级 | 百分比 | 含义 |
|---|---|---|
| A | 90%+ (108+) | 优秀——生产就绪的专家技能 |
| B | 80-89% (96-107) | 良好——需要小幅改进 |
| C | 70-79% (84-95) | 合格——有明确的改进路径 |
| D | 60-69% (72-83) | 低于平均——显著问题 |
| F | <60% (<72) | 差——需要根本性重新设计 |
步骤5：生成报告
# 技能评估报告：[技能名称]
## 总结
- **总分**：X/120 (X%)
- **等级**：[A/B/C/D/F]
- **模式**：[思维模式/导航/理念/流程/工具]
- **知识比例**：E:A:R = X:Y:Z
- **结论**：[一句话评估]
## 维度得分
| 维度 | 得分 | 满分 | 备注 |
|-----------|-------|-----|-------|
| D1：知识增量 | X | 20 | |
| D2：思维模式 vs 机制 | X | 15 | |
| D3：反模式质量 | X | 15 | |
| D4：规范合规性 | X | 15 | |
| D5：渐进式披露 | X | 15 | |
| D6：自由度校准 | X | 15 | |
| D7：模式识别 | X | 10 | |
| D8：实用可用性 | X | 15 | |
## 关键问题
[列出必须修复的、显著影响技能有效性的问题]
## 前3项改进
1. [最高影响改进及具体指导]
2. [第二优先级改进]
3. [第三优先级改进]
## 详细分析
[对于每个得分低于80%的维度，提供：
- 缺少或有问题的内容
- 技能中的具体示例
- 具体的改进建议]
常见失败模式
模式1：教程
症状：解释什么是PDF，Python如何工作，基本库用法
根本原因：作者假设技能应该“教”模型
修复：Claude已经知道这些。删除所有基本解释。
专注于专家决策、权衡和反模式。
模式2：倾倒
症状：SKILL.md有800+行，包含所有内容
根本原因：没有渐进式披露设计
修复：SKILL.md中的核心路由和决策树（理想<300行）
详细内容放在references/中，按需加载
模式3：孤儿引用
症状：存在引用目录但文件从未被加载
根本原因：没有明确的加载触发
修复：在工作流决策点添加“强制 - 读取整个文件”
添加“不要加载”以防止过度加载
模式4：复选框流程
症状：步骤1，步骤2，步骤3...机械流程
根本原因：作者以流程思考，而非思维框架
修复：转化为“在做X之前，问自己...”
专注于决策原则，而非操作顺序
模式5：模糊警告
症状：“小心”、“避免错误”、“考虑边缘情况”
根本原因：作者知道可能出错但未阐明具体内容
修复：具体的“绝不要”列表，包含具体示例和非显而易见的原因
“绝不要使用X，因为[需要经验才能学到的具体问题]”
模式6：隐形技能
症状：内容很好但技能很少被激活
根本原因：描述模糊，缺少关键词，或缺乏触发场景
修复：描述必须回答做什么、何时用，并包含关键词
“当...时使用” + 具体场景 + 可搜索术语
示例修复：
差： “帮助处理文档任务”
好： “创建、编辑和分析.docx文件。当处理
Word文档、修订或专业文档格式时使用。”
模式7：错误位置
症状：“何时使用此技能”部分在正文中，而非描述中
根本原因：误解三层加载
修复：将所有触发信息移到描述字段
正文仅在触发决策做出后才加载
模式8：过度工程化
症状：README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, CONTRIBUTING.md
根本原因：将技能视为软件项目
修复：删除所有辅助文件。只包含Agent完成任务所需的内容。
不要有关于技能本身的文档。
模式9：自由度不匹配
症状：创意任务用死板脚本，脆弱操作用模糊指导
根本原因：未考虑任务脆弱性
修复：创意任务高自由度（原则，而非步骤）
脆弱操作低自由度（确切脚本，无参数）
快速参考检查清单
┌─────────────────────────────────────────────────────────────────────────┐
│ 技能评估快速检查 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 知识增量（最重要）： │
│ [ ] 没有基本概念的“什么是X”解释 │
│ [ ] 没有标准操作的分步教程 │
│ [ ] 有非显而易见选择的决策树 │
│ [ ] 有只有专家才知道的权衡 │
│ [ ] 有来自真实世界经验的边缘情况 │
│ │
│ 思维模式 + 流程： │
│ [ ] 传递思维模式（如何思考问题） │
│ [ ] 有“在做X之前，问自己...”框架 │
│ [ ] 包含Claude不知道的领域特定流程 │
│ [ ] 区分有价值的流程和通用流程 │
│ │
│ 反模式： │
│ [ ] 有明确的“绝不要”列表 │
│ [ ] 反模式具体，而非模糊 │
│ [ ] 包含原因（非显而易见的原因） │
│ │
│ 规范（描述至关重要！）： │
│ [ ] 有效的YAML frontmatter │
│ [ ] name：小写，≤64字符 │
│ [ ] description回答：它做什么？ │
│ [ ] description回答：何时使用？ │
│ [ ] description包含触发关键词 │
│ [ ] description足够具体，让Agent知道何时使用 │
│ │
│ 结构： │
│ [ ] SKILL.md < 500行（理想<300） │
│ [ ] 重内容放在references/ │
│ [ ] 加载触发嵌入工作流 │
│ [ ] 有“不要加载”以防止过度加载 │
│ │
│ 自由度： │
│ [ ] 创意任务 → 高自由度（原则） │
│ [ ] 脆弱操作 → 低自由度（确切脚本） │
│ │
│ 可用性： │
│ [ ] 多路径场景的决策树 │
│ [ ] 有效的代码示例 │
│ [ ] 错误处理和备用方案 │
│ [ ] 覆盖边缘情况 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
元问题
评估任何技能时，始终回到这个基本问题：
“这个领域的专家看到这个技能会说：
‘是的，这捕捉了我花了多年才学到的知识’吗？”
如果答案是肯定的 → 技能有真正的价值。
如果答案是否定的 → 它压缩了Claude已知的内容。
最好的技能是压缩的专家大脑——它们将设计师10年的审美积累压缩成43行，或将文档专家的操作经验压缩成200行的决策树。
被压缩的必须是Claude没有的东西。否则，就是垃圾压缩。
自我评估说明
此技能（skill-judge）本身应通过评估：
- 知识增量：提供Claude自己不会生成的具体评估标准
- 思维模式：塑造如何思考技能质量，而不仅仅是检查清单项目
- 反模式：“评估时绝不要做”部分，包含具体禁止事项
- 规范：有效的frontmatter和全面的描述
- 渐进式披露：自包含，无需外部引用
- 自由度：适合评估任务的中等自由度
- 模式：遵循工具模式，包含决策框架
- 可用性：清晰的协议、报告模板、快速参考
将此技能与自身进行对比评估，作为校准练习。
