参考资料

• Agent Skills 规范
• MCP 规范

Skill（01） - Skill 是什么，解决什么问题

读完后，你应能完成以下任务：

• 绘制“Skill（01） - Skill 是什么，解决什么问题 / 先看一个让人头疼的场景”的关键对象与数据流，解释“「请帮我审查这段代码，重点看安全漏洞、命名规范、有没有写测试，输出用表格，每个问题标注严重等级……」”，并用源码位置、日志或 Trace 标注证据。
• 为“Skill（01） - Skill 是什么，解决什么问题 / Skill 到底是什么”设计正常与异常输入，验证“Skill 是一个有固定格式的文件夹，里面放一份叫 SKILL.md 的说明书。”，输出首个偏差位置与回归测试结果。
• 实现“Skill（01） - Skill 是什么，解决什么问题 / 它怎么就被「自动用上」了”的最小代码或配置，检验“这是 Skill 最妙的地方，也是新手最容易误解的地方。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：用大白话讲清 Skill 的本质，搞懂它和「提示词、插件、MCP」的区别，并拿到一张「要不要用 Skill」的判断清单。

一、先看一个让人头疼的场景

假设你每周都要让 Claude 帮你做「代码审查」。第一次你写了一大段提示词：

「请帮我审查这段代码，重点看安全漏洞、命名规范、有没有写测试，输出用表格，每个问题标注严重等级……」

效果不错。但问题来了：

• 下周再用，你得把这段提示词再翻出来贴一遍。
• 同事也想用，你得把它发给每个人。
• 你想加一条「检查 SQL 注入」，得挨个去改大家手里的版本。
• 提示词越写越长，每次对话都要重复占用上下文。

你会发现：好不容易调好的「干活方式」，没法沉淀下来反复用。

Skill 就是来解决这个问题的。

二、Skill 到底是什么

一句话：

Skill 是一个有固定格式的文件夹，里面放一份叫 SKILL.md 的说明书。当任务和它匹配时，Claude 会自动翻开说明书，按里面写好的流程和工具把活干好。

最小的样子长这样：

code-review/              # 技能文件夹，名字就是技能名
└── SKILL.md              # 说明书：告诉 Claude 这个技能干嘛、怎么干

SKILL.md 里面大概是这样（先扫一眼，看不懂没关系，后面章节会拆）：

---
name: code-review
description: 当用户需要审查代码质量、查找 bug、检查安全漏洞或规范问题时使用
---

# 代码审查

按以下维度逐项检查用户提供的代码：
1. 安全：SQL 注入、XSS、硬编码密钥
2. 正确性：边界条件、空值处理
3. 规范：命名、注释、测试覆盖

输出一张表格，每个问题标注严重等级（高/中/低）。

就这么简单——它本质上就是一份写给 AI 看的「岗位说明书」。

三、它怎么就被「自动用上」了

这是 Skill 最妙的地方，也是新手最容易误解的地方。

你不需要说「请用 code-review 技能」。你只要正常说：

「帮我看看这段登录代码有没有问题」

Claude 会扫一眼自己手上所有技能的 description，发现 code-review 的描述里写着「查找 bug、检查安全漏洞」，跟你的需求对上了，于是自动加载这份说明书，按里面的流程干活。

所以你可以把它理解成：一群随时待命的专家，Claude 根据你说的话，自动找对的那位上场。 这也是为什么后面第 05 章我们要专门讲「description 怎么写」——它就是这位专家的「招牌」，写不好就没人喊他上场。

四、和「提示词 / 插件 / MCP」有啥区别

新手最容易把这几个搞混。一张表说清：

对比项	普通提示词	Skill	MCP / 插件
是什么	你当场打的一段话	存成文件的「能力包」	外接的工具/数据源
能复用吗	不能，用完即走	能，文件一直在	能
怎么触发	手动打字	按需自动加载	按需调用
适合干嘛	临时、一次性需求	固定流程、反复要做的活	连接外部系统（数据库、API）
门槛	最低	低（写 Markdown）	较高（要写服务/代码）

记住三句话就够了：

• 提示词是「这一次怎么说」。
• Skill 是「这类活以后都这么干」。
• MCP 是「让 Claude 能摸到外面的工具和数据」。

它们不冲突，经常配合用：Skill 里完全可以让 Claude 去调用某个 MCP 工具。

五、什么时候该用 Skill（判断清单）

不是所有事都值得做成 Skill。对照下面这张清单，满足越多，越值得做：

• 这件事我会反复做（不是一次性的）
• 它有相对固定的流程或标准（不是每次都临场发挥）
• 我希望每次产出都稳定（而不是看 Claude 心情）
• 我想分享给别人 / 团队一起用
• 它需要配套的模板、清单或脚本

反过来，如果只是「我现在临时想问个问题」，那直接打字就行，别为了用而用。

六、常见误区

• 误区一：「Skill 是更高级的提示词，越长越好。」 错。Skill 讲究「单一职责 + 简洁」。一个技能只干一类事，正文能短则短（原因在第 06 章「渐进式披露」会讲透）。

• 误区二：「我得告诉 Claude 用哪个 Skill。」 不用。匹配是自动的，靠的是 description。你只管正常描述需求。

• 误区三：「Skill 能改变模型本身的能力。」 不能。它不训练模型、不改权重，只是在合适的时机，把一份写好的说明书喂给 Claude，引导它怎么做。

七、最佳实践

• 从一个你最常重复的任务开始。把你最近一周重复贴过 2 次以上的提示词，做成你的第一个 Skill。
• 一个技能只做一件事。「代码审查」和「写提交信息」是两个技能，别塞一起。
• 先能用，再优化。下一章我们就用 5 分钟跑通一个最小 Skill，先把闭环跑起来。

八、动手实践：01 章 Demo · 看懂一个真实 Skill + 自测「该不该做」

本 Demo 服务于第 01 章，帮你完成两件事：

1. 亲眼看懂一个真实 Skill 长什么样（带逐行注释）。
2. 自己判断手头的任务该不该做成 Skill。

本章是概念章，所以这个 Demo 不需要安装任何东西，打开文件看 + 对着清单勾选即可。

8.1 文件说明

02-skills是什么-demo/
├── README.md                  # 你正在看的说明
├── 带注释的SKILL示例.md        # 一份真实 Skill，逐行讲解每行在干嘛
└── 判断清单.md                 # 「该不该做成 Skill」自测表，照着勾

8.2 怎么用

1. 先读 带注释的SKILL示例.md，建立「Skill 原来长这样」的直观感受。
2. 再打开 判断清单.md，想一个你最近重复做过的任务，照着勾选，看它够不够格做成 Skill。
3. 如果勾中了 3 条以上 —— 恭喜，第 02 章我们就拿它来练手。

8.3 你会收获什么

• 不再把 Skill 想得很玄，知道它就是「文件夹 + 说明书」。
• 拿到一个可复用的判断标准，以后看到任务就能秒判「值不值得做成 Skill」。

8.4 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

带注释的SKILL示例.md

# 带注释的 SKILL 示例

下面是一份**真实可用**的 Skill 说明书。我们一行行拆开，告诉你每部分在干嘛。
（字段细节会在第 04、05 章讲透，这里只求「看个明白」。）

## 完整文件

````markdown
---
name: commit-message
description: 当用户写完代码改动、需要生成 Git 提交信息（commit message）时使用。适用于总结变更、按规范格式化提交说明的场景。
---

# 九、生成 Git 提交信息

根据用户提供的代码改动（diff 或描述），生成一条符合 Conventional Commits 规范的提交信息。

## 9.1 步骤
1. 判断改动类型：feat（新功能）/ fix（修 bug）/ docs（文档）/ refactor（重构）等。
2. 用一句话概括「做了什么」，控制在 50 字以内。
3. 如有必要，空一行后补充正文，说明「为什么改」。

## 9.2 输出格式
```text
<类型>: <一句话概括>

<可选的正文说明>
```

## 9.3 示例
输入：给登录接口加了图形验证码
输出：
feat: 登录接口增加图形验证码校验

防止暴力破解，连续失败 3 次后要求输入验证码。

逐段拆解

第 1 部分：frontmatter（开头被 --- 包起来的部分）

---
name: commit-message
description: 当用户写完代码改动、需要生成 Git 提交信息时使用……
---
```text

- `name`：技能的唯一名字，用小写+连字符。Claude 内部靠它区分技能。
- `description`：**最关键的一行**。它是「招牌」，Claude 靠读它来决定「这个活要不要喊这个技能上场」。
  - 注意它是**第三人称、讲场景**的写法：「当用户……时使用」。这是为了让匹配更准（第 05 章详解）。

> 🔑 记住：frontmatter 是「目录卡片」，Claude 平时只扫这部分来决定加不加载，所以它必须简短、精准。

### 第 2 部分：正文（`---` 之后的所有内容）

正文就是**真正的操作手册**，只有当技能被触发后，Claude 才会读它。这里我们写了：

- **一句话职责**：这个技能干嘛的。
- **步骤**：把活拆成有序的几步，让产出稳定。
- **输出格式**：明确规定长什么样，避免每次格式都飘。
- **示例**：给一个「输入→输出」的样例，这是让 AI 学样最有效的方式。

### 为什么这么排

- 把「触发用的信息」（description）和「执行用的信息」（正文）**分开**，是 Skill 的核心设计——既保证能被准确找到，又不浪费上下文。这个机制叫**渐进式披露**，第 06 章会专门讲。
- 「步骤 + 输出格式 + 示例」是写好正文的黄金三件套，几乎每个干活类 Skill 都用得上。

## 动手观察

对照上面的例子，回答三个问题（答案在心里想想就行）：

1. 如果用户说「帮我写个提交信息」，Claude 凭哪一行决定用这个技能？
2. 如果把 `description` 改成只写「提交信息」三个字，会有什么风险？
3. 「示例」那一段如果删掉，产出质量会怎样？

> 想完这三个问题，你其实已经摸到第 05 章（description）和第 06 章（渐进式披露）的门了。

判断清单.md

# 「该不该做成 Skill」自测清单

想一个你**最近一周内重复做过的任务**（比如：写周报、审代码、翻译文案、生成测试用例……），把它填在下面，然后照着勾。

---

## 我的候选任务

> 任务：______________________________________________
>
> （例：「每次写完功能都要手动整理一条 Git 提交信息」）

---

## 第一组：值不值得做（勾得越多越值得）

- [ ] 这件事我**会反复做**，不是一次性的
- [ ] 它有**相对固定的流程或标准**
- [ ] 我希望**每次产出都稳定**，不要忽好忽坏
- [ ] 我想**分享给同事 / 团队**一起用
- [ ] 它需要配套的**模板、清单或脚本**

**计分：勾中 ___ / 5**

- 勾中 **3 及以上** → 非常适合做成 Skill，第 02 章就拿它练手。
- 勾中 **1~2** → 可做可不做，先放着，等它变得更高频再说。
- 勾中 **0** → 直接打提示词就好，别为了用而用。

---

## 第二组：避坑检查（中了就要调整）

- [ ] ⚠️ 我想让这一个技能**干好几类不相干的事**
  → 拆开！一个技能只做一件事。
- [ ] ⚠️ 这个任务**每次都完全不一样**，没有可复用的套路
  → 它更适合临时提示词，不适合做成 Skill。
- [ ] ⚠️ 我以为做了 Skill 就能让 AI **学会它本来不会的知识**
  → 不行。Skill 是「引导怎么做」，不是「教模型新本领」。

---

## 填完之后

把你勾中 3 条以上的那个任务**记下来**。第 02 章「5 分钟跑通第一个 Skill」，我们就用真实的它来动手，而不是用玩具例子。

十、总结

• 先看一个让人头疼的场景：「请帮我审查这段代码，重点看安全漏洞、命名规范、有没有写测试，输出用表格，每个问题标注严重等级……」
• Skill 到底是什么：Skill 是一个有固定格式的文件夹，里面放一份叫 SKILL.md 的说明书。
• 它怎么就被「自动用上」了：这是 Skill 最妙的地方，也是新手最容易误解的地方。
• 和「提示词 / 插件 / MCP」有啥区别：| 是什么 | 你当场打的一段话 | 存成文件的「能力包」 | 外接的工具/数据源 |
• 什么时候该用 Skill（判断清单）：不是所有事都值得做成 Skill。
• 常见误区：误区一：「Skill 是更高级的提示词，越长越好。