第七章. Agent Skills 技能系统

本章学习路径

7.1. Skills 与其他功能的区别

上一章我们学会了创建斜杠命令。但斜杠命令有个特点：必须显式调用。

“其实就是相当于给AI定义不同的角色,是吗? 但是这样子的话,它和subagent有什么区别呢?”

可以理解为这个新的技能功能其实就是给 AI 定义不同的角色和风格。区别在于，Sub Agent 更像是一个真正独立的小助手，有自己独立的运行逻辑和上下文处理。而技能更像是给同一个 AI 主体戴上不同的“帽子”或设定不同的“模式”，让它在同一个环境里按照不同的风格来工作。简单来说，Sub Agent 是真正的独立个体，而技能只是让同一个 AI 切换不同的工作风格而已。

“我想让 Claude 更智能一点——当我说’帮我处理这个 PDF’时，它自动知道该怎么做，而不是我每次都要输入 /pdf。”

这就是 技能Claude 自动匹配并应用的能力模块 的用途。

7.1.1. Skills vs 斜杠命令

选择建议：

• 如果是 “我想执行某个固定操作” → 用斜杠命令
• 如果是 “我想让 Claude 具备某种能力” → 用 Skills

7.1.2. Skills vs 子代理

选择建议：

• 如果任务需要大量探索，不想污染主对话 → 用子代理
• 如果只是给 Claude 增加某种知识或能力 → 用 Skills

7.1.3. Skills vs CLAUDE.md

选择建议：

• 如果是 “所有对话都需要知道的信息” → 放 CLAUDE.md
• 如果是 “特定场景才需要的能力” → 用 Skills

7.1.4. 本节小结

Skills 的定位：

7.2. 创建 Skill

理解了 Skills 的定位，现在来看如何创建一个 Skill。

7.2.1. SKILL.md 文件格式

Skill 的核心是一个 SKILL.md 文件，包含 YAML frontmatter 和 Markdown 内容。

存放位置：

基本结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: skill-name
description: 描述这个 Skill 的用途和触发场景
allowed-tools: Tool1, Tool2
---

# Skill 名称

## 使用说明

这里描述 Claude 应该如何使用这个 Skill。

## 示例

这里提供具体的使用示例。

Frontmatter 字段：

7.2.2. 支持文件的渐进式披露

Skill 可以包含多个支持文件，实现 渐进式披露——核心信息放在 SKILL.md，详细参考放在其他文件。

目录结构示例：

1
2
3
4
5
6

.claude/skills/pdf-processing/
├── SKILL.md           # 核心说明（必须）
├── FORMS.md           # 表单处理详细说明
├── REFERENCE.md       # API 参考文档
└── scripts/
    └── validate.py    # 辅助脚本

在 SKILL.md 中引用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

## 快速开始

基本用法见下方说明。

## 详细参考

- 表单处理详情见 [FORMS.md](FORMS.md)
- API 参考见 [REFERENCE.md](REFERENCE.md)

## 辅助工具

验证 PDF 格式：
python scripts/validate.py input.pdf

Claude 会先读取 SKILL.md，只有在需要详细信息时才会读取其他文件。这样可以节省上下文空间。

7.2.3. allowed-tools 工具限制

allowed-tools 字段可以限制 Skill 激活时 Claude 能使用的工具。

示例：只读 Skill

1
2
3
4
5

---
name: code-analyzer
description: 分析代码结构和质量，不做任何修改
allowed-tools: Read, Grep, Glob
---

这个 Skill 激活时，Claude 只能读取和搜索，不能修改文件。

示例：数据处理 Skill

1
2
3
4
5

---
name: data-processor
description: 处理 CSV 和 JSON 数据文件
allowed-tools: Read, Write, Bash
---

这个 Skill 可以读写文件和执行命令，但不能使用网络相关工具。

7.2.4. 本节小结

创建Skill 的核心要素：

7.3. 实战：创建代码解释 Skill

理论讲完了，现在来实战创建一个专门解释代码的 Skill。

7.3.1. 需求分析

我们想要一个 Skill，它能够：

• 当用户说 “解释这段代码” 时自动激活
• 用 ASCII 图表展示代码结构
• 用生活化的类比解释抽象概念
• 只读不写——只负责解释，不修改代码

7.3.2. 编写 SKILL.md

步骤 1：创建目录

1

mkdir -p ~/.claude/skills/code-explainer

步骤 2：创建 SKILL.md

创建文件 ~/.claude/skills/code-explainer/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

---
name: code-explainer
description: 代码解释专家。当用户请求解释代码、理解代码逻辑、分析代码结构时自动激活。擅长用图表和类比让复杂代码变得易懂。
allowed-tools: Read, Grep, Glob
---

# 代码解释专家

## 核心原则

1. **先整体后局部**：先给出代码的整体作用，再逐步深入细节
2. **图表优先**：用 ASCII 图表展示数据流、调用关系
3. **类比辅助**：用生活化的类比解释抽象概念
4. **分层解释**：根据代码复杂度，分层次讲解

## 解释模板

### 第一步：一句话总结

用一句话概括这段代码的核心作用。

### 第二步：结构图解

用 ASCII 图表展示代码结构：


┌─────────────┐     ┌─────────────┐
│   输入      │ ──► │   处理      │ ──► 输出
└─────────────┘     └─────────────┘


### 第三步：生活类比

用一个生活场景来类比代码的工作方式。

### 第四步：逐行解析

对关键代码行进行详细解释。

## 注意事项

- 不要假设用户有任何前置知识
- 遇到专业术语必须解释
- 如果代码有 Bug，在解释时指出

7.3.3. 添加支持文件

为了让 Skill 更强大，我们可以添加一些支持文件。

创建类比库

创建文件 ~/.claude/skills/code-explainer/ANALOGIES.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 常用类比库

## 数据结构类比

- **数组**：一排储物柜，每个柜子有编号
- **链表**：寻宝游戏，每个线索指向下一个位置
- **栈**：一摞盘子，只能从顶部取放
- **队列**：排队买票，先来先服务
- **哈希表**：图书馆索引卡，通过关键词快速定位
- **树**：家族族谱，有父节点和子节点
- **图**：城市地铁网络，站点之间相互连接

## 设计模式类比

- **单例模式**：一个国家只有一个总统
- **工厂模式**：汽车工厂，告诉它要什么车型，它生产出来
- **观察者模式**：订阅报纸，有新内容自动送到家
- **策略模式**：导航软件，可以选择最快、最短、避开高速等不同路线
- **装饰器模式**：给手机贴膜、戴壳，不改变手机本身但增加功能

## 并发类比

- **线程**：餐厅里的服务员，多个服务员可以同时服务不同桌
- **锁**：厕所门锁，一次只能一个人用
- **死锁**：两个人在窄路相遇，都等对方先让路
- **线程池**：银行柜台，固定数量的窗口服务排队的客户

在 SKILL.md 中引用

在 SKILL.md 的末尾添加：

1
2
3

## 参考资料

如需更多类比灵感，参考 [ANALOGIES.md](ANALOGIES.md)。

7.3.4. 本节小结

创建 Skill 的完整流程：

7.4. 本章总结与 Skills 速查

本章我们学习了 Agent Skills 技能系统——让 Claude 自动识别并应用特定能力。核心思想是：把领域知识封装成可复用的模块，让 Claude 在合适的时机自动调用。

7.4.1. 场景速查：遇到这些情况，直接用

场景 1：创建简单的只读 Skill

创建 ~/.claude/skills/analyzer/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11

---
name: analyzer
description: 代码分析专家。分析代码质量、复杂度、潜在问题。
allowed-tools: Read, Grep, Glob
---

分析代码时，关注以下维度：
1. 代码复杂度
2. 潜在 Bug
3. 性能问题
4. 可维护性

场景 2：创建带支持文件的 Skill

1
2
3
4
5

~/.claude/skills/api-designer/
├── SKILL.md           # 核心说明
├── REST.md            # REST API 设计规范
├── GRAPHQL.md         # GraphQL 设计规范
└── EXAMPLES.md        # 示例集合

场景 3：查看所有可用 Skills

1

› 你有哪些 Skills？

Claude 会列出所有已加载的 Skills。

场景 4：测试 Skill 是否生效

用自然语言描述一个匹配 Skill 描述的任务：

1

› 帮我解释一下这段代码的工作原理

如果 code-explainer Skill 配置正确，Claude 会自动应用它。