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