skill-judge

Skill Judge

基于官方规范以及从 17+ 官方示例中总结的模式，对 Agent Skill 进行全面质量评估。

---

核心理念

什么是 Skill？

Skill 绝对不是教程或指南。Skill 是一种知识外显化机制（knowledge externalization mechanism）。

传统 AI 的知识被死死锁在模型参数里。想要赋予模型新能力，传统路径是：

传统模式：收集数据 → 上 GPU 集群 → 训练模型 → 部署新版本
成本：10,000 - 1,000,000+ 美元
周期：数周到数月

Skill 完全颠覆了这一点：

Skill 模式：编辑 SKILL.md → 保存 → 下一次调用即刻生效
成本：0 元
周期：秒级生效

这就是从“训练 AI”到“教育 AI”的范式转变 —— 就像给模型插上了一个免训练、即插即用的 LoRA 适配器。你只需用自然语言修改 Markdown 文件，模型的行为就会随之改变。

核心公式

优质 Skill = 专家独占知识 − Claude 已知常识

Skill 的核心价值取决于它的知识增量（Knowledge Delta） —— 即 Skill 提供的干货与模型已有认知之间的差距。

• 专家独占知识：决策树、权衡取舍（Trade-offs）、边缘场景（Edge cases）、反模式（Anti-patterns）、特定领域的思考框架 —— 这些都是需要多年一线实战经验才能积累起来的硬核门道。
• Claude 已知常识：基础概念、标准库用法、通用编程模式、常规最佳实践。

如果一个 Skill 还在滔滔不绝地解释“什么是 PDF”或“如何写一个 for 循环”，那就是在重复压缩 Claude 早就掌握的知识。这是极大的 Token 浪费 —— 上下文窗口是与 System Prompt、对话历史、其他 Skill 以及用户 Request 共享的公共资源，寸土寸金。

Tool 与 Skill 的区别

概念	本质	功能	示例
Tool（工具）	模型能做什么	执行具体动作	bash、read_file、write_file、WebSearch
Skill（技能）	模型懂得怎么做	指导决策与思路	PDF 处理、MCP 开发、frontend design

Tool 划定了能力边界 —— 没有 bash 工具，模型就无法执行命令。
Skill 注入了专业认知 —— 没有 frontend-design Skill，模型做出来的 UI 就是一股大厂通用 AI 味。

能力公式：

通用 Agent + 顶级 Skill = 领域专家级 Agent

同样的 Claude 模型，挂载不同的 Skill，就能瞬间变身为不同领域的顶尖专家。

Skill 中的三类知识

在评估时，将各个章节划分为以下三类：

类型	定义	处理策略
专家级（Expert）	Claude 确实不知道的硬核干货	必须保留 —— 这是 Skill 的核心价值所在
唤醒级（Activation）	Claude 知道但未必能联想到的点	精简保留 —— 仅作为临门一脚的提示
冗余级（Redundant）	Claude 早就烂熟于心的废话	坚决删除 —— 纯粹浪费 Token

Skill 设计的精髓在于：最大化专家级内容、极简留存唤醒级内容、无情砍掉冗余级内容。

---

评估维度（总分 120 分）

D1：知识增量（20 分）—— 核心维度

最关键的评估维度。Skill 是否注入了真正的专家级干货？

得分	评分标准
0-5 分	满篇都是 Claude 已知的基础常识（什么是 X、如何写代码、标准库入门教程等）
6-10 分	掺杂模式：虽有部分专家干货，但被大量显而易见的内容稀释
11-15 分	绝大部分为专家干货，冗余内容极少
16-20 分	纯粹的知识增量 —— 每一段内容都对得起它消耗的 Token

避雷红线（出现即直接判定 ≤5 分）：

• 出现“什么是 [基础概念]”类的名词解释章节
• 标准操作的手把手入门教程
• 解释常用第三方库的基础用法
• 空洞泛化的最佳实践（如“保持代码整洁”、“注意异常处理”）
• 行业标准术语的科普定义

高分亮点（高知识增量的显著标志）：

• 针对非显而易见选择的决策树（如“当 X 失败时尝试 Y，因为 Z”）
• 只有老手才知道的权衡取舍（如“A 方案更快，但 B 方案能妥善处理边缘场景 C”）
• 来自一线真实实战踩坑得出的边缘场景
• 明确指出“绝不要做 X，因为 [非显而易见的原因]”
• 特定领域的专业思考框架

评估思考题：

1. 逐段盘问：“这玩意儿 Claude 真的不知道吗？”
2. 如果在做解释，反思：“这是在给 Claude 传授新知，还是在替 Claude 炒冷饭？”
3. 统计专家级、唤醒级与冗余级段落的比例。

---

D2：思维范式 + 领域特定流程（15 分）

Skill 是否在传授专家心智与思维模式的同时，附带了必要的领域特定操作流程？

专家与新手之间的区别本质上不是“懂不懂如何操作”，而是“如何思考问题”。但当 Claude 缺乏领域特定的流程知识时，仅有思考模式也是远远不够的。

核心区分：

类型	示例	价值
思维模式（Thinking patterns）	“在开始设计之前先问自己：是什么让这个设计脱颖而出？”	高 —— 塑造决策思维
领域特定流程（Domain-specific procedures）	“OOXML 工作流：解包 → 编辑 XML → 校验 → 打包”	高 —— Claude 未必掌握
通用废话流程（Generic procedures）	“步骤 1：打开文件；步骤 2：编辑；步骤 3：保存”	低 —— Claude 早就知道

得分	评分标准
0-3 分	只有 Claude 早就掌握的通用流水线步骤
4-7 分	包含领域具体流程，但缺乏高维度的思考框架
8-11 分	兼顾平衡：具备良好的思维模式 + 领域特定工作流
12-15 分	专家水准：既重塑了思考方式，又提供了 Claude 无法自推的特定流程

什么是真正有价值的流程：

• Claude 未在训练集中充分学习的工作流（如最新工具、私有或专有系统）
• 非显而易见的正确执行顺序（例如“必须在打包之前进行校验，而不是之后”）
• 极其容易遗漏的关键环节（例如“修改后必须重新计算公式”）
• 特定领域的标准步骤序列（例如 MCP Server 的 4 阶段开发流程）

什么是无价值的冗余流程：

• 通用的文件读写基础操作（打开、读取、写入、保存）
• 标准的编程结构（循环、条件分支、基础异常捕获）
• 文档齐全且普及的常用库调用流程

专家级的思维模式示例：

在执行 [操作] 之前，先思考以下问题：
- **目标**：这解决了什么痛点？受众是谁？
- **约束**：存在哪些隐性限制条件？
- **差异化**：是什么让这个方案令人眼前一亮？

有价值的领域流程示例：

### 修订留痕工作流（Claude 无法凭空猜出此顺序）
1. 转换为 Markdown：`pandoc --track-changes=all`
2. 将文本映射至 XML：在 document.xml 中 grep 目标文本
3. 按 3-10 个为一组分批实施修改
4. 打包并核验：检查是否所有修改均已正确生效

冗余的通用流程示例：

步骤 1：打开文件
步骤 2：定位到目标章节
步骤 3：进行修改
步骤 4：保存并测试

检验标准：

1. 它是否告诉了 Claude 该思考什么？（思维模式）
2. 它是否指引了 Claude 如何完成它原本未知的特定任务？（领域流程）

优秀的 Skill 会在必要时将二者有机结合。

---

D3：反模式质量（15 分）

Skill 是否提供了精准强效的“严禁行为（NEVER）清单”？

为什么这至关重要：专家的知识有一半在于“知道不要做什么”。资深设计师看到白底配紫色渐变会本能地感到油腻 ——“太有一股 AI 味了”。这种对“绝对不能踩的坑”的直觉，完全来自于无数次实战踩坑后的惨痛教训。

但 Claude 没踩过这些坑。它不知道 Inter 字体已经被滥用，也不懂得紫色渐变早已成了 AI 生成内容的代名词。因此，好的 Skill 必须明确且毫不留情地规定这些“绝对禁忌”。

得分	评分标准
0-3 分	完全未提及任何反模式或禁忌事项
4-7 分	泛泛而谈的警告（如“避免出错”、“注意边界”、“小心谨慎”）
8-11 分	列出了具体的 NEVER 严禁清单，并附带了一定解释
12-15 分	专家级的反模式清单，且清晰阐明了“为什么” —— 全是实战教训换来的真知灼见

专家级反模式示例（具体 + 阐明原因）：

绝不要（NEVER）使用千篇一律的 AI 调性设计，例如：
- 滥用的字体系列（Inter、Roboto、Arial）
- 陈词滥调的配色方案（尤其是白底搭配紫色渐变）
- 完全可预测的呆板布局与组件结构
- 给所有元素都套上默认圆角（border-radius）

敷衍的反模式示例（含糊不清、毫无干货）：

尽量避免犯错。
注意处理边缘情况。
不要写糟糕的代码。

检验标准：一名行业老手看到这份反模式清单后，是会感叹“太扎心了，这都是当年血淋淋的教训”，还是会吐槽“这不是懂的都懂的废话吗”？

---

D4：规范合规性 —— 重点在于 Description（15 分）

Skill 是否符合官方格式规范要求？特别关注 Description 的撰写质量。

得分	评分标准
0-5 分	缺少 Frontmatter 或格式存在严重语法错误
6-10 分	包含 Frontmatter，但 Description 表述模糊或信息缺失
11-13 分	Frontmatter 合规，Description 交代了“是什么（WHAT）”，但未能凸显“何时用（WHEN）”
14-15 分	完美：Description 全面涵盖 WHAT、WHEN 以及触发关键词

Frontmatter 规范要求：

• name：全小写字母、数字及连字符（hyphens），长度 ≤ 64 字符
• description：权重最高的字段 —— 直接决定了 Skill 能否被成功触发调用

---

为什么 Description 是最核心的字段：

┌─────────────────────────────────────────────────────────────────────┐
│  SKILL 触发激活流程                                                  │
│                                                                     │
│  用户 Request → Agent 扫描所有 Skill 的 Description → 决定激活哪一个 │
│                 （只读取 Description，不读正文！）                     │
│                                                                     │
│  若 Description 未能匹配 → Skill 永远不会被加载                      │
│  若 Description 模棱两可 → 本该调用的场景下 Skill 可能会哑火          │
│  若 Description 缺少关键词 → 该 Skill 对 Agent 来说完全不可见        │
└─────────────────────────────────────────────────────────────────────┘

残忍的真相：一个正文写得再完美的 Skill，如果 Description 烂掉，那就毫无用处 —— 因为它根本没机会被激活。Description 是向 Agent 宣告“在这些场景下请召唤我”的唯一机会。

---

Description 必须明确回答三个问题：

1. WHAT（是什么）：这个 Skill 具备哪些功能？（功能特性）
2. WHEN（何时用）：在什么具体场景下应当使用？（触发场景）
3. KEYWORDS（关键词）：哪些核心词汇应当触发该 Skill？（检索关键词）

高质量 Description 示例（三大要素俱全）：

description: "Comprehensive document creation, editing, and analysis with support
for tracked changes, comments, formatting preservation, and text extraction.
When Claude needs to work with professional documents (.docx files) for:
(1) Creating new documents, (2) Modifying or editing content,
(3) Working with tracked changes, (4) Adding comments, or any other document tasks"

解析：

• WHAT：文档创建、编辑、分析、修订留痕、批注
• WHEN：“当 Claude 需要处理专业文档……用于：(1)……(2)……(3)……”
• KEYWORDS：.docx 文件、修订留痕、专业文档

低质量 Description 示例（要素缺失）：

description: "处理文档相关功能"

痛点分析：

• WHAT：太宽泛（“文档相关功能” 到底指具体什么？）
• WHEN：缺失（Agent 在什么情况下应该调用它？）
• KEYWORDS：缺失（没有指定 .docx，没有具体场景词）

另一个极差示例：

description: "A helpful skill for various tasks"

完全废话 —— Agent 完全无从判断何时去激活它。

---

Description 质量检查清单：

• [ ] 列出了明确具体的技能点（而不是笼统写“帮助处理 X”）
• [ ] 包含了清晰的触发场景说明（“在……时使用”、“当用户要求……时”）
• [ ] 包含了可检索的核心关键词（文件拓展名、领域专业词汇、动作动词）
• [ ] 指向足够精确，使 Agent 能准确定位调用的最佳时机
• [ ] 涵盖了必须使用该 Skill 的场景（而不只是“可以使用”）

---

D5：渐进式加载（Progressive Disclosure）（15 分）

Skill 是否实现了合理的内容分层架构？

Skill 的加载机制分为三层：

Layer 1：元数据层（常驻内存）
         仅包含 name + description