name: skill-judge description: 评估Agent技能设计质量，对照官方规范和最佳实践。在审查、审计或改进SKILL.md文件和技能包时使用。提供多维评分和可操作的改进建议。

技能评估器

基于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。

公式：

通用代理 + 优秀技能 = 领域专家代理

同一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未训练的工作流（新工具、专有系统）
非明显正确顺序（如“验证BEFORE打包，而非之后”）
容易错过的关键步骤（如“编辑后MUST重新计算公式”）
领域特定序列（如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	专家级反模式带WHY——只有经验教会的

专家反模式（具体 + 理由）：

绝不使用通用AI生成美学如：
- 过度使用字体家族（Inter、Roboto、Arial）
- 陈词滥调配色方案（特别是白色背景上紫色渐变）
- 可预测布局和组件模式
- 所有内容默认圆角半径

弱反模式（模糊，无理由）：

避免犯错。
小心边缘案例。
不要编写坏代码。

测试：专家读反模式列表会说“是的，我学这个很艰难”？还是“这对每个人都明显”？

D4: 规范合规——尤其是描述（15分）

技能是否遵循官方格式要求？特别关注描述质量。

分数	标准
0-5	缺少frontmatter或无效格式
6-10	有frontmatter但描述模糊或不完整
11-13	有效frontmatter，描述有WHAT但在WHEN上弱
14-15	完美：全面描述，包含WHAT、WHEN和触发关键词

Frontmatter要求：

name：小写，仅字母数字 + 连字符，≤64字符
description：最关键的字段——决定技能是否被使用

为什么描述是最重要字段：

┌─────────────────────────────────────────────────────────────────────┐
│  技能激活流程                                                      │
│                                                                     │
│  用户请求 → 代理看到所有技能描述 → 决定哪个激活                   │
│                 （仅描述，非主体！）                                 │
│                                                                     │
│  如果描述不匹配 → 技能永不加载                                    │
│  如果描述模糊 → 技能可能应该触发时没触发                          │
│  如果描述缺少关键词 → 技能对代理不可见                            │
└─────────────────────────────────────────────────────────────────────┘

残酷真相：内容完美但描述差的技能无用——它永远不会被激活。描述是告诉代理“在这些情况下用我”的唯一机会。

描述必须回答三个问题：

WHAT：技能做什么？（功能）
WHEN：什么情况下应用？（触发场景）
关键词：什么术语应触发此技能？（可搜索术语）

优秀描述（所有三元素）：

description: "综合文档创建、编辑和分析，支持跟踪更改、评论、格式保留和文本提取。当Claude需要处理专业文档（.docx文件）时：
(1) 创建新文档，(2) 修改或编辑内容，
(3) 处理跟踪更改，(4) 添加评论，或其他文档任务"

分析：

WHAT：创建、编辑、分析、跟踪更改、评论
WHEN：“当Claude需要处理…时：(1)…(2)…(3)…”
关键词：.docx文件、跟踪更改、专业文档

差描述（缺少元素）：

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

问题：

WHAT：模糊（“文档相关功能”——具体什么？）
WHEN：缺失（什么时候代理该用它？）
关键词：缺失（无“.docx”、无具体场景）

另一个差示例：

description: "各种任务的有用技能"

这无用——代理不知何时激活。

描述质量检查表：

[ ] 列出具体能力（不仅“帮助X”）
[ ] 包括明确触发场景（“用时…”、“当用户要求…”）
[ ] 包含可搜索关键词（文件扩展、领域术语、动作动词）
[ ] 具体到代理知道EXACTLY何时使用
[ ] 包括此技能必须用的场景（不仅“可以用”）

D5: 渐进披露（15分）

技能是否实现适当内容分层？

技能加载有三层：

第1层：元数据（总在内存）
         仅名称 + 描述
         ~100令牌每技能

第2层：SKILL.md主体（触发后加载）
         详细指南、代码示例、决策树
         理想：< 500行

第3层：资源（按需加载）
         scripts/、references/、assets/
         无限制

分数	标准
0-5	所有内容倾倒在SKILL.md（>500行，无结构）
6-10	有引用但不清楚何时加载
11-13	良好分层，有MANDATORY触发器
14-15	完美：决策树 + 明确触发器 + “不加载”指导

对于有引用目录的技能，检查加载触发器质量：

触发器质量	特点
差	引用列在末尾，无加载指导
中等	一些触发器但未嵌入工作流
好	MANDATORY触发器在工作流步骤中
优秀	场景检测 + 条件触发器 + “不加载”

加载问题：

加载太少 ◄─────────────────────────────────► 加载太多
- 引用未使用                        - 浪费上下文空间
- 代理不知何时加载                  - 不相关信息稀释关键内容
- 知识存在但从未访问                - 不必要的令牌开销

良好加载触发器（嵌入工作流）：

### 创建新文档

**MANDATORY - 读取整个文件**：进行前，必须完整读取
[`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	整个过程中完美自由度校准

自由度谱：

任务类型	应有	原因	示例技能
创造性/设计	高自由度	多种有效方法，差异化是价值	前端设计
代码审查	中自由度	原则存在但需判断	代码审查
文件格式操作	低自由度	一个错误字节损坏文件，一致性关键	docx、xlsx、pdf

高自由度（基于文本指令）：

承诺BOLD美学方向。选择极端：极简主义、
最大化混乱、复古未来、有机自然...

中自由度（伪代码或参数化）：

审查优先级：
1. 安全漏洞（必须修复）
2. 逻辑错误（必须修复）
3. 性能问题（应修复）
4. 可维护性（可选）

低自由度（具体脚本、精确步骤）：

**MANDATORY**：使用`scripts/create-doc.py`中的精确脚本
参数：--title "X" --author "Y"
不要修改脚本。

测试：问“如果代理犯错，后果是什么？”

高后果 → 低自由度
低后果 → 高自由度

D7: 模式识别（10分）

技能是否遵循已建立的官方模式？

通过分析17个官方技能，识别5个主要设计模式：

模式	~行数	关键特点	示例	何时使用
心态	~50	思维 > 技术，强“绝不”列表，高自由度	前端设计	需要品味的创造性任务
导航	~30	最小SKILL.md，路由到子文件	内部通信	多个不同场景
哲学	~150	两步：哲学 → 表达，强调工艺	画布设计	需要原创性的艺术/创作
过程	~200	分阶段工作流，检查点，中自由度	mcp构建器	复杂多步项目
工具	~300	决策树，代码示例，低自由度	docx、pdf、xlsx	特定格式的精确操作

分数	标准
0-3	无可识别模式，混乱结构
4-6	部分遵循模式，显著偏差
7-8	清晰模式，轻微偏差
9-10	适当模式的精湛应用

模式选择指南：

任务特点	推荐模式
需要品味和创造力	心态（~50行）
需要原创性和工艺质量	哲学（~150行）
多个不同子场景	导航（~30行）
复杂多步项目	过程（~200行）
特定格式的精确操作	工具（~300行）

D8: 实际可用性（15分）

代理能否有效使用此技能？

分数	标准
0-5	混淆、不完整、矛盾或未测试指导
6-10	可用但明显缺口
11-13	常见案例的清晰指导
14-15	全面覆盖，包括边缘案例和错误处理

检查：

决策树：对于多路径场景，有明确指导选择哪条路径？
代码示例：它们实际工作吗？还是破坏的伪代码？
错误处理：如果主方法失败？提供后备方案？
边缘案例：覆盖不寻常但现实的场景？
可操作性：代理能立即行动，还是需要弄清楚？

良好可用性（决策树 + 后备）：

| 任务 | 主要工具 | 后备 | 何时使用后备 |
|------|-------------|----------|----------------------|
| 读取文本 | pdftotext | PyMuPDF | 需要布局信息 |
| 提取表格 | camelot-py | tabula-py | camelot失败 |

**常见问题**：
- 扫描PDF：pdftotext返回空白 → 先使用OCR
- 加密PDF：权限错误 → 使用带密码的PyMuPDF

差可用性（模糊）：

使用适当工具处理PDF。
正确处理错误。
考虑边缘案例。

评估时绝不做的

绝不仅因“看起来专业”或格式良好给高分
绝不忽略令牌浪费——每个冗余段落应导致扣分
绝不让长度打动你——43行技能可能优于500行技能
绝不跳过心理测试决策树——它们实际导致正确选择吗？
绝不因“但提供有用上下文”原谅解释基础
绝不忽视缺少反模式——如果无“绝不”列表，那是显著缺口
绝不假设所有程序都有价值——区分领域特定与通用
绝不低估描述字段——差描述 = 技能永不使用
绝不将“何时使用”信息仅放在主体中——代理加载前仅看到描述

评估协议

步骤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 | |

## 关键问题
[列出必须修复的显著影响技能有效性的问题]

## 前三改进
1. [最高影响改进，带具体指导]
2. [第二优先级改进]
3. [第三优先级改进]

## 详细分析
[对每个分数<80%的维度提供：
- 缺少或有问题的
- 技能中具体示例
- 具体改进建议]

常见失败模式

模式1：教程

症状：解释什么是PDF、Python如何工作、基本库使用
根本原因：作者假设技能应“教”模型
修复：Claude已知这个。删除所有基础解释。
     专注于专家决策、权衡和反模式。

模式2：倾泻

症状：SKILL.md 800+行，一切包含
根本原因：无渐进披露设计
修复：核心路由和决策树在SKILL.md（<300行理想）
     详细内容在references/中，按需加载

模式3：孤儿引用

症状：引用目录存在但文件从不加载
根本原因：无明确加载触发器
修复：在工作流决策点添加“MANDATORY - 读取整个文件”
     添加“不加载”以防止过度加载

模式4：勾选框程序

症状：步骤1、步骤2、步骤3...机械程序
根本原因：作者以程序思考，而非思维框架
修复：转变为“做X前，问自己...”
     专注于决策原则，而非操作序列

模式5：模糊警告

症状：“小心”、“避免错误”、“考虑边缘案例”
根本原因：作者知道会出问题但未具体表述
修复：具体“绝不”列表，带具体示例和非明显理由
     “绝不使用X因为[需要经验学习的特定问题]”

模式6：不可见技能

症状：内容好但技能很少激活
根本原因：描述模糊、缺少关键词或缺乏触发场景
修复：描述必须回答WHAT、WHEN和包含关键词
     “用时...” + 具体场景 + 可搜索术语

示例修复：
差：“帮助文档任务”
好：“创建、编辑和分析.docx文件。用时处理Word文档、跟踪更改或专业文档格式化。”

模式7：错误位置

症状：“何时使用此技能”部分在主体，非描述
根本原因：误解三层加载
修复：将所有触发信息移到描述字段
     主体仅在触发决策后加载

模式8：过度工程

症状：README.md、CHANGELOG.md、INSTALLATION_GUIDE.md、CONTRIBUTING.md
根本原因：将技能视为软件项目
修复：删除所有辅助文件。仅包括代理任务所需。
     无技能本身文档。

模式9：自由度不匹配

症状：创造性任务的刚性脚本，脆弱操作的模糊指导
根本原因：未考虑任务脆弱性
修复：创造性高自由度（原则，非步骤）
     脆弱操作低自由度（精确脚本，无参数）

快速参考检查表

┌─────────────────────────────────────────────────────────────────────────┐
│  技能评估快速检查                                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  知识差异（最重要）：                                                  │
│    [ ] 无“什么是X”解释基础概念                                         │
│    [ ] 无标准操作逐步教程                                              │
│    [ ] 有非明显选择的决策树                                            │
│    [ ] 有只有专家知道的权衡                                            │
│    [ ] 有来自真实世界经验的边缘案例                                    │
│                                                                         │
│  心态 + 程序：                                                        │
│    [ ] 传递思维模式（如何思考问题）                                    │
│    [ ] 有“做X前，问自己...”框架                                       │
│    [ ] 包括Claude不知道的领域特定程序                                  │
│    [ ] 区分有价值程序与通用程序                                        │
│                                                                         │
│  反模式：                                                              │
│    [ ] 有明确“绝不”列表                                                │
│    [ ] 反模式具体，非模糊                                              │
│    [ ] 包括WHY（非明显理由）                                           │
│                                                                         │
│  规范（描述关键！）：                                                  │
│    [ ] 有效YAML frontmatter                                           │
│    [ ] name：小写，≤64字符                                            │
│    [ ] 描述回答：做什么？                                              │
│    [ ] 描述回答：何时使用？                                            │
│    [ ] 描述包含触发关键词                                              │
│    [ ] 描述具体到代理知道何时使用                                      │
│                                                                         │
│  结构：                                                                │
│    [ ] SKILL.md < 500行（理想<300）                                    │
│    [ ] 重内容在references/                                             │
│    [ ] 加载触发器嵌入工作流                                            │
│    [ ] 有“不加载”以防止过度加载                                        │
│                                                                         │
│  自由度：                                                              │
│    [ ] 创造性任务 → 高自由度（原则）                                   │
│    [ ] 脆弱操作 → 低自由度（精确脚本）                                 │
│                                                                         │
│  可用性：                                                              │
│    [ ] 多路径场景的决策树                                              │
│    [ ] 工作代码示例                                                    │
│    [ ] 错误处理和后备                                                  │
│    [ ] 覆盖边缘案例                                                    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

元问题

评估任何技能时，始终回到这个基本问题：

“此领域专家看此技能会说： ‘是的，这捕获了我多年学习的知识’吗？”

如果答案是是 → 技能有真正价值。如果答案是否 → 它在压缩Claude已知内容。

最佳技能是压缩的专家大脑——它们将设计师10年美学积累压缩为43行，或将文档专家操作经验压缩为200行决策树。

压缩的必须是Claude没有的。否则，是垃圾压缩。

自我评估注

此技能（skill-judge）应自身通过评估：

知识差异：提供Claude不会自己生成的特定评估标准
心态：塑造如何思考技能质量，不仅检查表项目
反模式：“评估时绝不做的”部分带具体不要
规范：有效frontmatter带全面描述
渐进披露：自包含，无需外部引用
自由度：中自由度适合评估任务
模式：遵循工具模式带决策框架
可用性：清晰协议、报告模板、快速参考