全篇不会教你怎么去给Agent创建Skill，而是教会你什么是好的Skill、坏的Skill以及究其原因。

什么是Agent Skill

一个根本性的误解

大多数人听到“Agent Skill”，首先想的是：教会AI去做某件事情

但是你有没有想过，现在的大模型已经不知道喂了多少东西了，像维基百科、Word问单号、github代码仓

这些，都不需要你教给大模型

那么Skill到底是个什么？

Skill是知识的外化机制

从作用机制上来说，Skill其实教会模型怎么去做？

传统AI，知识都被锁在了模型参数当中，你如果像给模型去塞一些新的技能？怎么做？

传统方式：
收集数据 → 设置 GPU 集群 → 参数训练 → 部署新版本
成本：$10,000 - $1,000,000+
周期：数周到数月

Skill改变了这一切：

Skill 方式：
编辑 SKILL.md 文件 → 保存 → 下次触发时生效
成本：$0
周期：即时

就好像一个小女孩，她会十位数以内的加法，以及99乘法口诀，现在你想让她学会“乘法竖式题”，skill就是教会她怎么进位怎么填空。

这就从“训练AI”变成了“教育AI”的范式转变

Tool VS Skill

有读者在学习的过程中，把这两个概念混为一谈，现在我们对他进行澄清：

工具是能力的边界-没有bash工具，模型根本就无法执行命令。

Skill则是技巧的注入- 没有前端设计的SKill，模型写出的UI将会是千篇一律。

核心公式：

通用 Agent + 优秀 Skill = 特定领域的专家 Agent

因此，有文章指出，Skill的质量决定了这个模型基座能够发挥到什么程度。一个优秀的Skill，能够让通用模型能够在特定的领域超越没有Skill加持的更强模型

评判Skill的好坏

标准一：Token效率

来源：Anthropic官方指导的Skill-creator规范

上下文窗口是一个公共资源，一个skill占用的token过多，会极度挤压其他内容的空间---包括系统提示、对话历史、其他skill的信息、用户的实际请求。

因此如果你写了一段“什么是PDF”的解释时，你就是在浪费这个公共资源。基座已经知道什么是PDF了，这100个token可以用来存放更有用的东西

如何判断：

在书写skill的段落时，问自己三个问题：

1、 模型真的不知道这个是什么吗？

2、删掉他会影响任务完成吗？

3、这100个token能换来什么价值

核心公式：

好 Skill = 专家独有的知识 - Claude 已有的知识

注：我怎么知道模型知不知道？Zero-Shot 直接试探直接下达指令，看它是否产生幻觉。或者是否胡言乱语？

标准二：Skill更注重思维方式

大佬分析了17个官方的Skill实例，特别是frontend-design

官方给出的design只有43行，他没有教模型如何去写CSS，也没有去解释什么是flexbox，没有列出step1、step2...

Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic...
- **Differentiation**: What makes this UNFORGETTABLE?

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto),
cliched color schemes (purple gradients on white backgrounds)...

这个skill激发的是大模型的设计师思维方式-这就是新手和专家的区别

深层逻辑：

这就是专家和新手的区别：不在于“会不会操作”，而在于“如何思考问题”，一个资深的设计师和初学者，都会写CSS，但是设计师在写第一行代码之前，脑子里就有了一个清晰的审美方向，用户场景、差异化定位

标准三：发模式清单-明确什么不能做

分析了官方Skill的普遍特征，发现几乎有些的官方skill都明确的包含了Never清单

frontend-design：

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial),
cliched color schemes (particularly purple gradients on white backgrounds),
predictable layouts and component patterns...

深层逻辑：

专家知识知道的是“知道什么能做”，另一半知道“什么绝对不能做”

一个资深设计师看到紫色渐变配白色背景，会本能地皱眉——"太 AI 感了"。这种"什么不能做"的直觉，是踩过无数坑之后形成的。

那么大模型知不知道呢，答案是肯定的，他当然不知道，因此我们需要给他设限

如何判断：

你的 Skill 里有没有明确的"NEVER"清单？有没有告诉 Agent 什么是"垃圾做法"？

标准四：Description触发机制-何时被激活

skill-creator规范：官方原文

This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill. Include both what the Skill does and specific triggers/contexts for when to use it. Include all "when to use" information here - Not in the body. The body is only loaded after triggering.

Skill在agent运行的时候什么时候被调度激活？深层次的分析Skill的三层加载机制

Layer 1: Metadata（始终在内存中）
         只有 name + description
         ~100 tokens / skill

Layer 2: SKILL.md Body（触发后才加载）
         详细指南、代码示例、决策树
         < 5000 tokens

Layer 3: Resources（按需加载）
         scripts/, references/, assets/
         无限制

因此，关键在于：description是唯一可见的部分，agent根据description决定是否激活这个Skill，如果description太模糊，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 it does）
• 列出触发场景（when to use）
• 包含关键词（.docx files, tracked changes）

标准五：自由度匹配

官方skill-creator规范

根据任务的“脆弱性”和“多变性”来匹配相应的精确度：
高自由度（基于文本的指令）： 适用于存在多种可行路径、且决策高度依赖于上下文的场景。
中等自由度（伪代码或带参数的脚本）： 适用于存在首选模式（惯用法），但允许一定程度变化的场景。
低自由度（特定的脚本，极少参数）： 适用于操作流程极其脆弱且易出错、对一致性要求极高的场景。

深层次的挖掘：

意思就是，你不同的任务需要不同程度的约束。例如：

创意设计任务：需要高自由度，你给agent一个审美方向，让他自由发挥，过度约束会扼杀掉创意

文档格式操作任务：需要低自由度。Word文档的OOXML格式有严格的规范，一个字符写错可能会导致文件损坏。

对应关系：

如何判断：

问自己：这个任务容错率高还是低？如果 Agent 做错一步，后果是什么？

容错率高 → 给原则，不给步骤 容错率低 → 给脚本，少参数

标准六：skill中reference能否被正确加载

很多 Skill 有详细的 reference 文档，但 Agent 不读。或者读太多。

深层原因：

不同 Agent 对 Skill 机制的训练程度不同：

• Claude 对 Skill 机制有专门训练，会适度主动加载
• 大多数 Agent 没有专门训练，不会主动加载
• 有些 Agent 过于积极，一次性加载太多

你不能假设 Agent 会"聪明地"按需加载。你必须显式设计加载触发机制。

解决方案：

你需要在关键节点嵌入强制加载指令。官方Docx skill做法：

### Creating New Document

**MANDATORY - READ ENTIRE FILE**: Before proceeding, you MUST read
[`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish.
**NEVER set any range limits when reading this file.**

"MANDATORY"、"MUST"、"NEVER" 不是装饰词，是确保 Agent 执行的关键信号。

Skill等级

可以将agent skill分为三个等级：简单、中等、复杂三个维度，依据是否包含其他文件来进行区分（非SKILL.md）

简单的skill，只包含skill.md

中等、复杂skill：包含references和scripts

通用Skill类型

极简心智型

代表：frontend-design（43 行）

结构特点：

• 不教技术细节，传递思维方式
• 全部内容自包含在 SKILL.md 中
• 没有 references 目录
• 强调品味、差异化、反模式

赋能：

把一个通用的、写出千篇一律 UI 的 Agent，变成一个有审美品味的设计师 Agent。

这个 Agent 在写代码之前会先思考：这个界面要解决什么问题？用户是谁？什么能让它令人难忘？它会主动避免"AI 感"设计，追求独特性。

适用场景：

• 需要创意和品味的任务
• 差异化来自"怎么想"而非"知道什么"
• 不需要大量领域特定知识

不需要加载触发机制——43 行内容一次性加载，无需分层。

工具操作型

代表：docx（197 行）、xlsx、pptx、pdf

结构特点：

• 决策树快速路由到正确工作流
• MANDATORY 强制加载指令
• 详细的代码示例
• 大量 reference 文档（每个 300-600 行）
• 低自由度，精确步骤

赋能：

把一个通用的、可能会把 Word 文档写坏的 Agent，变成一个能精确操作复杂文件格式的专家 Agent。

这个 Agent 知道：创建新文档用 docx-js，编辑现有文档用 OOXML 直接操作，处理修订痕迹用 redlining 工作流。它知道每种操作的具体步骤，不会犯破坏文件的错误。

适用场景：

• 文件格式操作
• 操作容易出错，需要精确指导
• 需要大量领域特定知识

需要精心设计的加载触发——决策树根据任务类型路由，每个工作流开始前强制加载对应文档。

流程导向型

代表：mcp-builder（237 行）

结构特点：

• 清晰的多阶段工作流（如四阶段）
• 每个阶段有具体的产出和检查点
• reference 按阶段/按选择组织
• 中等自由度

赋能：

把一个通用的、可能遗漏关键步骤的 Agent，变成一个能系统性构建复杂项目的工程师 Agent。

这个 Agent 知道构建 MCP 服务器要经过：研究规划 → 实现 → 测试 → 评估四个阶段。每个阶段它知道要做什么、产出什么、什么时候可以进入下一阶段。

适用场景：

• 复杂的多步骤任务
• 需要阶段性检查点
• 有多种技术选择（如 TypeScript vs Python）

需要阶段性加载触发——进入每个阶段时加载对应的 reference 文档。

哲学+执行型

代表：canvas-design（130 行）、algorithmic-art

结构特点：

• 两步流程：Philosophy（创建理念）→ Express（执行创作）
• 反复强调工艺品质和大师级执行
• 给予创意空间
• reference 是参考示例，非必需

赋能：

把一个通用的、输出平庸作品的 Agent，变成一个有创作哲学的艺术家 Agent。

这个 Agent 不会直接开始画画。它会先创建一个设计哲学——"Brutalist Joy"或"Chromatic Silence"——然后用这个哲学指导视觉表达。它追求的是"看起来像花了无数小时精心制作"的品质。

适用场景：

• 创意生成任务
• 需要独特性和原创性
• 品质比效率更重要

加载触发可选——核心工作流自包含在 SKILL.md，reference 只是参考示例。

导航型

代表：internal-comms（33 行）

结构特点：

• SKILL.md 极简，只是路由器
• 详细内容在 examples/ 子目录中
• 快速识别场景，路由到对应文件

## How to use this skill

1. **Identify the communication type** from the request
2. **Load the appropriate guideline file**:
   - `examples/3p-updates.md` - 进度/计划/问题更新
   - `examples/company-newsletter.md` - 公司通讯
   - `examples/faq-answers.md` - 常见问题回答
   - `examples/general-comms.md` - 其他类型
3. **Follow the specific instructions** in that file

把一个通用的 Agent，变成一个能处理多种场景的专业写手 Agent。

这个 Agent 收到"帮我写周报"时，会识别这是 3P 更新，然后加载对应的指南，按照公司的格式和风格来写。

适用场景：

• 有多个明确的子场景
• 每个子场景有独立的详细指南
• 不需要同时加载所有场景

需要简单路由触发——识别场景类型，加载对应文件。

Skill触发机制

Skill 设计的核心理念是按需加载上下文——把详细知识存在 reference 文件里，需要时才加载，保持 context window 精简。

但是现实情况是，Agent会读很多不该读的文档或者不经常读该读的文档

方案一：嵌入语法

可以在工作流的步骤中，强制嵌入加载指令

### 创建新文档

**MANDATORY - READ ENTIRE FILE**：在继续之前，你必须完整阅读
[`docx-js.md`](docx-js.md)（约 500 行）。
**绝对不要设置任何行数限制。**

方案二：条件触发路由表

| 任务类型 | 必须加载 | 不要加载 |
|----------|----------|----------|
| 创建新文档 | `docx-js.md` | `ooxml.md`, `redlining.md` |
| 简单编辑 | `ooxml.md` | `docx-js.md`, `redlining.md` |
| 修订痕迹 | `redlining.md` | `docx-js.md` |

可以在SKILL中设置一个这样的路由表，让agent自行参考

Skill审视

写完一个Skill，可以去过一遍如下的清单

基础规范
[ ] 有 YAML frontmatter，包含 name 和 description
[ ] description 包含"做什么"和"什么时候用"
[ ] SKILL.md < 500 行

内容质量
[ ] 没有解释 Claude 已知的基础概念
[ ] 没有机械的 Step 1, 2, 3
[ ] 有明确的反模式清单（NEVER list）
[ ] 有决策树或选择指导（如果有多种路径）
[ ] 有常见陷阱和边缘情况

加载机制（仅有 reference 的 Skill）
[ ] 每个 reference 有明确的加载触发条件
[ ] 触发条件嵌入在工作流步骤中
[ ] 有防止过度加载的机制

自由度
[ ] 创意任务 → 高自由度（原则而非步骤）
[ ] 脆弱操作 → 低自由度（精确脚本）