Claude Code Skill：最佳实践与创建规范

本篇是这一系列中关于 Skill 的最后一篇文章。上一篇里，我们已经见识过 Skill 的威力，但在真实项目里，需求远不止那些示例。除了更细致的场景，还更需要一套「通用的 Skill 创建方法」。只有这样，每个人才能为自己的项目打造真正好用、可复用的 Skill。接下来就顺着我的思路，一起把「如何创建 Skill」这件事，打磨成一套可落地的最佳实践。

功能单元

准确地分析 Skill 的能力边界非常关键：范围太大，会变成一个「什么都想干却什么都干不好」的巨石 Skill；范围太小，又会让 Skill 数量爆炸，后期维护成本很高。

所以，功能单元的合理设计，其实更像是在搭积木、搭 pipeline。

参考内容

这部分大家应该都不陌生：AI 的行为，很大程度上取决于它能看到的历史数据、文档和各种参考材料。这些内容会直接影响 Skill 生成的质量和风格。我给这套思路起了一个名字——「文档驱动开发」。下面就从几类关键的参考内容展开说明：

1. CLAUDE.md 知识库

没错，这里指的就是 CLAUDE.md 这个知识库文件。对大多数项目来说，都非常有必要维护这样一份「全局生效」的知识库：AI 每次都会读取它，用来统一项目的规范和约定。建议你定期迭代更新其中的内容，用来：

• 降低 AI 误解需求、犯低级错误的概率
• 提高回复的一致性和可预期性
• 让规范本身产生复利效应（越写越全、越用越顺）

2. 结果参照

Skill 中的示例目录，本质上是给 AI 的「标准答案样本」。通过这些示例，你可以直接告诉 AI：

• 结果大概长什么样
• 应该采用怎样的格式和结构
• 内容需要细到什么程度、覆盖哪些关键点

3. 明确的需求与背景说明

每个 Skill 都应该有一份专门的「需求清单」，用来尽可能完整地说明：

• 任务的背景和目标
• 大致的处理过程
• 可用的输入信息（来源、格式、范围）
• 期望的输出形式和精度

你可以完全按照程序设计的方式来思考：这个 Skill 需要哪些「参数」、哪些是必填、哪些是可选、默认值是什么。你给 AI 的输入越清晰、边界越明确，最终生成的 Skill 就越稳。

小结

上面 1、2 两部分负责给 AI 设定「规范」和「结果参考」，而第 3 部分则是尽可能把「输入信息」说明白。三者结合起来，才能让 Skill 在你的项目里既靠谱又可控。

Plan 模式

相比直接让 AI 上来就执行，然后再在结果上反复修改，我更推荐先让它「先写 Plan 再执行」。也就是先和 AI 一起把整体方案、步骤、风险点对齐好，再进入真正的开发阶段，这点和我们日常做项目、写方案的习惯是高度一致的。

Review 与迭代

Skill 几乎不可能「一次生成就完美」。更现实的做法是，把每一次使用中暴露出来的问题，当成优化 Skill 的素材。根据这些实际错误和偏差，持续更新：

• SKILL.md 中的说明和约束
• 参考示例和输出样本
• CLAUDE.md 里的全局规范

长期来看，这些小步迭代会让 Skill 越用越顺手，也能逐渐贴合你团队自己的工程习惯。

终极形态

我心目中 Skill 的终极形态，有点像 n8n 这类工作流编排工具：先做好一堆颗粒度合适的「积木」，再通过编排和组合，把它们串成一条条自动化的工作流。届时，Skill 不再只是「单点能力」，而是可以拼接起来的「完整生产线」。

Skill Creator

这里强烈推荐使用官方提供的、专门用来创建其他 Skill 的 Skill——Skill Creator。

github.com/anthropics/skills/tree/...

需求清单模板

先说明一下：我下面给出的这份需求清单模板会比较完整，你不需要一开始就把所有内容都写满。

刚开始创建 Skill 时，可以只填写最基础、最关键的部分；当你发现生成的 Skill 不够准确、不够稳定时，再逐步补充和迭代细节就好。

这份模板大致包含以下十个主要部分：
1. 基本信息 - Skill 名称、描述、触发条件
2. 使用场景 - 核心用例和边界情况
3. 输入规范 - 必需/可选输入、格式要求、验证规则
4. 输出规范 - 输出类型、文件详情、内容结构、示例
5. 工作流程 - 主流程、决策点、错误处理
6. 资源需求 - 脚本、参考文档、资源文件
7. 依赖和约束 - 项目内/外部依赖、约束条件
8. 验证方式 - 自动/手动验证、常见问题排查
9. 参考资料 - 现有实现、外部文档、相关 Skill
10. 补充说明 - 特殊需求、优先级、其他备注

# Skill 创建需求清单模板（详细版）

> 此模板用于向 Skill Creator 提供完整的需求描述。每个部分都有详细的子项和填写指南。

---

## 一、基本信息

### 1.1 Skill 名称

**要求**：
- 格式：hyphen-case（小写字母、数字、连字符）
- 长度：最多 64 个字符
- 示例：`my-skill-name`, `pdf-converter`, `api-generator`

**填写**：
```
名称：
```

### 1.2 Skill 描述

**要求**：
- 长度：最多 1024 个字符
- 必须回答两个问题：
 - "这个 Skill 是做什么的？"
 - "什么时候应该使用它？"

**填写**：
```
描述：
```

### 1.3 触发条件

**说明**：Claude 根据什么判断应该使用这个 Skill
**填写**：
```
当用户需要 __________ 时使用此 Skill当检测到 __________ 情况时使用此 Skill```

---

## 二、使用场景

### 2.1 核心用例（必填，至少 1 个）

**用例 1**：
```
场景名称：

用户输入是什么：
- 输入类型：（文档/命令/配置/其他）
- 输入内容示例：

期望输出是什么：
- 输出类型：（代码/文档/操作/其他）
- 输出内容示例：

执行步骤：
1.
2.
3.
```

**用例 2**（可选）：
```
场景名称：

用户输入是什么：

期望输出是什么：

执行步骤：
```

**用例 3**（可选）：
```
场景名称：

用户输入是什么：

期望输出是什么：

执行步骤：
```

### 2.2 边界情况

**不处理的情况**：
```
这个 Skill 不应该处理：
1.
2.
3.
```

**错误处理**：
```
当输入不完整时：
当输入格式错误时：
当依赖不存在时：
```

---

## 三、输入规范

### 3.1 必需输入

| 序号 | 输入名称 | 类型 | 描述 | 示例值 |
|------|----------|------|------|--------|
| 1 | | | | |
| 2 | | | | |
| 3 | | | | |

### 3.2 可选输入

| 序号 | 输入名称 | 类型 | 描述 | 默认值 | 示例值 |
|------|----------|------|------|--------|--------|
| 1 | | | | | |
| 2 | | | | | |

### 3.3 输入格式要求

**文件类型要求**：
```
支持的文件格式：
文件大小限制：
编码要求：
```

**内容格式要求**：
```
必须包含的字段/结构：
格式示例：
```

### 3.4 输入验证规则

```
规则 1：
规则 2：
规则 3：
```

---

## 四、输出规范

### 4.1 输出类型（勾选所有适用项）

- [ ] 生成新文件
- [ ] 修改现有文件
- [ ] 执行命令/操作
- [ ] 返回信息/数据
- [ ] 调用外部服务

### 4.2 输出文件详情（如生成文件）

**文件 1**：
```
文件名/路径模式：
文件格式：
生成位置：
命名规则：
```

**文件 2**（如有）：
```
文件名/路径模式：
文件格式：
生成位置：
命名规则：
```

### 4.3 输出内容结构

**代码文件结构**（如适用）：
```
- 头部信息：
- 导入部分：
- 类型定义：
- 主体逻辑：
- 导出部分：
```

**文档文件结构**（如适用）：
```
- 标题格式：
- 章节结构：
- 必需章节：
```

### 4.4 输出示例（必填）

提供一个完整的期望输出示例：

```
（粘贴完整的输出示例）
```

### 4.5 输出质量要求

```
代码风格：
命名规范：
注释要求：
格式化规则：
```

---

## 五、工作流程

### 5.1 主流程

```
阶段 1：准备阶段
├── 步骤 1.1：
├── 步骤 1.2：
└── 步骤 1.3：

阶段 2：处理阶段
├── 步骤 2.1：
├── 步骤 2.2：
└── 步骤 2.3：

阶段 3：输出阶段
├── 步骤 3.1：
├── 步骤 3.2：
└── 步骤 3.3：
```

### 5.2 决策点

**决策点 1**：
```
条件：
如果 A → 执行 X如果 B → 执行 Y否则 → 执行 Z```

**决策点 2**（如有）：
```
条件：
如果 A →如果 B →否则 →```

### 5.3 错误处理流程

```
错误类型 1：
- 检测方式：
- 处理方式：
- 用户提示：

错误类型 2：
- 检测方式：
- 处理方式：
- 用户提示：
```

---

## 六、资源需求

### 6.1 脚本文件 (scripts/)
**是否需要脚本**：[ ] 是 [ ] 否

**脚本 1**：
```
文件名：
编程语言：
主要功能：
输入参数：
输出结果：
使用场景：
```

**脚本 2**（如有）：
```
文件名：
编程语言：
主要功能：
输入参数：
输出结果：
使用场景：
```

### 6.2 参考文档 (references/)
**是否需要参考文档**：[ ] 是 [ ] 否

**文档 1**：
```
文件名：
文档类型：（API文档/规范说明/示例集合/其他）
主要内容：
来源：
用途：
```

**文档 2**（如有）：
```
文件名：
文档类型：
主要内容：
来源：
用途：
```

### 6.3 资源文件 (assets/)
**是否需要资源文件**：[ ] 是 [ ] 否

**资源 1**：
```
文件名：
文件类型：（模板/图片/配置/其他）
用途：
使用方式：
```

**资源 2**（如有）：
```
文件名：
文件类型：
用途：
使用方式：
```

---

## 七、依赖和约束

### 7.1 项目内依赖

**依赖的文件**：
```
1\. 文件路径：
 依赖原因：
2\. 文件路径：
 依赖原因：```

**依赖的模块/函数**：
```
1\. 模块名：
 使用方式：
2\. 模块名：
 使用方式：```

### 7.2 外部依赖

**API/服务依赖**：
```
1\. 服务名：
 用途： 认证方式：
2\. 服务名：
 用途： 认证方式：```

**工具依赖**：
```
1\. 工具名：
 版本要求：
2\. 工具名：
 版本要求：```

### 7.3 约束条件

**技术约束**：
```
编程语言限制：
框架版本要求：
运行环境要求：
```

**业务约束**：
```
数据处理限制：
安全合规要求：
性能要求：
```

**编码规范**：
```
代码风格：
命名约定：
文件组织：
```

---

## 八、验证方式

### 8.1 自动验证

**语法/编译验证**：
```
验证命令：
预期结果：
```

**单元测试**：
```
测试命令：
测试覆盖范围：
```

**集成测试**：
```
测试命令：
测试场景：
```

### 8.2 手动验证

**检查清单**：
```
[ ] 检查项 1：
[ ] 检查项 2：
[ ] 检查项 3：
[ ] 检查项 4：
```

**验收标准**：
```
标准 1：
标准 2：
标准 3：
```

### 8.3 常见问题排查

```
问题 1：
- 症状：
- 原因：
- 解决方案：

问题 2：
- 症状：
- 原因：
- 解决方案：
```

---

## 九、参考资料

### 9.1 现有实现参考

```
参考文件 1：
- 路径：
- 参考价值：

参考文件 2：
- 路径：
- 参考价值：
```

### 9.2 外部文档

```
文档 1：
- 链接/位置：
- 内容摘要：

文档 2：
- 链接/位置：
- 内容摘要：
```

### 9.3 相关 Skill
```
Skill 1：
- 名称：
- 关系：（相似/依赖/互补）

Skill 2：
- 名称：
- 关系：
```

---

## 十、补充说明

### 10.1 特殊需求

```
（任何无法归类到上述类别的特殊需求）
```

### 10.2 优先级说明

```
必须实现：
1.
2.

可选实现：
1.
2.

未来扩展：
1.
2.
```

### 10.3 其他备注

```
（其他需要 Skill Creator 了解的信息）
```

---

## ✅ 提交前检查清单

**必填项**：
- [ ] 1.1 Skill 名称
- [ ] 1.2 Skill 描述
- [ ] 1.3 触发条件
- [ ] 2.1 至少 1 个核心用例
- [ ] 4.4 输出示例

**推荐填写**：
- [ ] 3.1 必需输入
- [ ] 4.2 输出文件详情
- [ ] 5.1 主流程
- [ ] 8.2 手动验证检查清单

**可选填写**：
- [ ] 其他所有项目（根据 Skill 复杂度决定）

---

## 📝 快速填写模式

如果时间有限，至少提供以下信息：

```markdown
## Skill 名称
[填写]

## 描述和触发条件
[填写]

## 核心用例
输入：[填写]
输出：[填写]
步骤：[填写]

## 输出示例
[粘贴完整示例]
```

这里再重点讲一下关于 assets/ 目录这一块。

assets/ 目录是什么？

它的作用是：存放「不需要加载到上下文中、但会被 Claude 直接拿来作为最终输出素材」的文件。

和其他目录的区别大概是这样：

典型使用场景包括：

1. 模板文件 - 如 assets/slides.pptx（PPT 模板）
2. 品牌资源 - 如 assets/logo.png（公司 logo）
3. 样板代码 - 如 assets/frontend-template/（前端项目模板）
4. 字体文件 - 如 assets/font.ttf
5. 可直接复制修改的样例文档

Skill Creator 如何使用这些资源？

结合 SKILL.md 示例：当你为类似 frontend-webapp-builder 这种 Skill 设计「帮我建一个 todo app」的能力时：
1. 写 web 前端时，很多基础 HTML/React 结构其实每次都差不多
2. 把这些通用结构放到一个 assets/hello-world/ 模板目录里，会非常省事

执行时，Claude 会在运行 Skill 的过程中，直接把 assets/ 里的文件复制到目标目录，再按具体需求进行少量修改，而不是先把文件内容读入上下文再从零生成。

这样做的核心优势是：

• 节省 token：不占用上下文窗口
• 保证一致性：模板和资源始终保持统一格式
• 提高效率：复制 + 微调通常比完全重写更可靠

简单说：assets/ 就是 Skill 的「素材库」，Claude 可以直接拿来用，不需要先读一遍再重写。

这里我就不再展开具体示例了。你可以直接复制前面的 Skill Creator 需求清单模板，交给 AI 帮你生成一份真正贴合自己项目的需求清单。

执行

已经写完实际的需求清单后：

/skill-creator 使用这个需求清单完成Skill创建

总结

回到一开始的目标：不是随便「整两个 Skill 玩玩」，而是把 Skill 当成你项目里的基础设施，做到可复用、可组合、可演进。

整篇文章其实围绕三件事展开：

• 把 Skill 切成合适的功能单元，像搭积木一样可组合
• 用文档驱动：CLAUDE.md + 示例结果 + 需求清单，把规则、输入、输出说清楚
• 接受「先 Plan 再执行，持续 Review 和迭代」这一套工程化流程

在此基础上，再借助 Skill Creator、需求清单模板和 assets/ 这类「素材库」，你就可以逐渐搭出一套属于自己团队的 Skill 体系——从一个个小能力，长成真正能支撑日常开发、运营、协作的工作流。

如果你已经有了第一个 Skill，不妨就从它开始，按照文中的思路倒推一遍：补上缺失的文档、示例和约束，然后再交给 Claude 帮你把 Skill 升级一版。真正的威力，往往是在第二版、第三版之后才会慢慢显现出来。

本作品采用《CC 协议》，转载必须注明作者和本文链接