如果你用过 Claude Code，大概率有过这种体验：每次开新对话，都得重新解释一遍「我要什么格式」、「按什么流程来」、「别忘了检查 XXX」。

Skill 就是为了解决这个问题——教一次，永远会。

本文深度拆解 Anthropic 官方 Skill 写作文档，结合一线开发者的踩坑经验，手把手教你如何写好一个 Skill。

一、Skill 是什么？

1.1 核心定义

Skill 的本质，就是一个文件夹，里面包含：

• SKILL.md（必须）：YAML 前言 + Markdown 指令
• scripts/（可选）：可执行脚本（Python、Bash 等）
• references/（可选）：按需加载的参考文档
• assets/（可选）：模板、字体、图标等资源

1.2 Skill vs CLAUDE.md

很多人分不清 Skill 和 CLAUDE.md 的区别：

1.3 厨房与菜谱的比喻

Anthropic 用了一个很形象的比喻：

• MCP 是厨房：提供灶台、食材、刀具，让 Claude 能连接外部服务
• Skill 是菜谱：告诉 Claude 拿到工具后，该按什么步骤、什么标准来完成任务

没有 Skill 的 MCP，就像给你一个装满食材的厨房，但没有任何菜谱。你每次都得从头告诉厨师做什么菜、放多少盐、几分钟出锅。

二、Skill 文件结构详解

2.1 目录结构

your-skill-name/              # kebab-case，禁止空格/大写/下划线
├── SKILL.md                  # 必须，大小写敏感
├── scripts/                  # 可选：可执行脚本
├── references/               # 可选：参考文档
└── assets/                   # 可选：模板、资源文件

2.2 硬性规则

• 文件名必须是 SKILL.md，不接受任何变体（SKILL.MD、skill.md 均无效）
• 文件夹名必须 kebab-case：code-reviewer ✅，CodeReviewer ❌，code_reviewer ❌
• 不要在 Skill 文件夹内放 README.md

2.3 存储位置

Skill 可以放在不同位置，作用范围和优先级不同：

三、SKILL.md 文件详解

3.1 文件结构

Skill 文件分为两大区域：

• 配置区：YAML Frontmatter，用 --- 包裹
• 内容区：Markdown 格式，写具体指令

3.2 配置区（YAML Frontmatter）

这是整个 Skill 最关键的部分，决定了 Skill 何时被加载。

---
name: code-reviewer                    # 必需，kebab-case
description: |                          # 必需，<1024 字符
  Review code for quality, security, and best practices.
  Use when asked to review code, check for bugs, audit security.
allowed-tools: "Read Grep Glob"         # 可选，限制工具
model: claude-opus-4-7                  # 可选，指定模型
effort: high                            # 可选：low/medium/high/max
---

3.3 Description 字段：决定 Skill 是否自动加载

Description 是整个 Skill 最重要的部分，它决定了 Claude 什么时候加载你的 Skill。

好的 Description 公式：

做什么 + 什么时候用 + 触发词

示例对比：

一个好的 Description 应该包含：

• 场景：什么情况下使用这个 Skill
• 关键词：用户说什么词时触发
• 触发条件：具体的触发规则

3.4 内容区（Markdown）

内容区是 Skill 的操作手册，需要明确三个问题：

• 何时调用：什么情况下使用这个 Skill
• 教什么：要完成什么任务
• 怎么教：具体的步骤和规则

推荐写作顺序：

1. 先写任务定义（这个 Skill 要解决什么问题）
2. 再定义输出格式（期望的输出结构）
3. 明确限制规则（不要做什么）
4. 最后提供示例（给 Claude 参考）

四、完整 Skill 示例

4.1 代码审查 Skill

---
name: code-reviewer
description: |
  Review code for quality, security, and best practices.
  Use when asked to review code, check for bugs, audit security,
  or analyze implementation quality.
allowed-tools: "Read Grep Glob"
---

# Code Reviewer

## Review Workflow
1. Read the code - Understand purpose and context
2. Identify issues - Security, bugs, performance
3. Prioritize findings - Critical > Major > Minor > Suggestion

## Output Format

### Critical Issues
- [Line 42] SQL injection vulnerability
  ```python
  # Before: query = f"SELECT * FROM users WHERE id = {user_id}"
  # After: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
  ```

### Major Issues
...

### Minor Issues
...

### Suggestions
...

## Review Checklist
- [ ] Security: No injection vulnerabilities
- [ ] Performance: No N+1 queries
- [ ] Error handling: All exceptions caught
- [ ] Type safety: Proper type hints
- [ ] Documentation: Complex logic explained

4.2 API 文档生成 Skill

---
name: api-doc-generator
description: |
  Generate API documentation from code.
  Use when user asks to "document API", "create API docs",
  or when working with FastAPI/Flask/Django endpoints.
allowed-tools: "Read Glob"
---

# API Documentation Generator

## Task
Generate comprehensive API documentation following OpenAPI 3.0 spec.

## Output Structure
```yaml
endpoint: /api/v1/users
method: POST
summary: Create a new user
parameters:
  - name: name
    type: string
    required: true
responses:
  201:
    description: User created successfully
  400:
    description: Invalid input
```

## Rules
1. Always include request/response examples
2. Mark required fields clearly
3. Document error responses
4. Include authentication requirements

五、Skill 写作原则

5.1 原则一：先写 Description

Description 决定了 Skill 的触发效果，应该最先写、反复打磨。

5.2 原则二：一个 Skill 只解决一件事

不要把多个不相关的功能塞进一个 Skill。Skill 应该像 Unix 哲学一样：做一件事，并做好。

❌ 反面示例：一个 Skill 既做代码审查，又做文档生成，还做测试

✅ 正确做法：拆成三个 Skill：code-reviewer、doc-generator、test-writer

5.3 原则三：Skill 和 CLAUDE.md 分开

不要把项目特定的配置写进 Skill，Skill 应该是可复用的能力模块。

• Skill：教 Claude「怎么写代码审查」
• CLAUDE.md：告诉 Claude「这个项目的代码规范是什么」

5.4 原则四：渐进式披露

Skill 采用三层加载机制，写作时要考虑：

• 第一层（YAML）：只放最精简的触发信息
• 第二层（SKILL.md 正文）：放完整的操作指令
• 第三层（references/）：放详细的参考资料

5.5 原则五：提供具体示例

Claude 从示例中学习的效果比从规则中学习更好。每个 Skill 都应该包含：

• 输入示例
• 输出示例
• 边界情况处理示例

六、高级技巧

6.1 控制 Skill 的调用方式

通过 frontmatter 字段控制谁可以调用 Skill：

6.2 使用脚本扩展能力

Skill 可以包含可执行脚本：

my-skill/
├── SKILL.md
└── scripts/
    └── validate.py    # Claude 可以执行这个脚本

6.3 引用外部资源

把详细文档放在 references/ 目录，需要时再加载：

my-skill/
├── SKILL.md
└── references/
    ├── style-guide.md
    └── api-reference.md

七、常见错误与解决方案

7.1 错误一：Description 写得太模糊

症状：Skill 该触发时不触发，不该触发时乱触发

解决：按照「做什么 + 什么时候用 + 触发词」公式重写

7.2 错误二：Skill 功能过于复杂

症状：一个 Skill 做太多事，Claude 不知道用哪个功能

解决：拆分成多个单一职责的 Skill

7.3 错误三：缺少具体示例

症状：Claude 理解了规则但输出质量不稳定

解决：添加输入/输出示例，展示边界情况处理

7.4 错误四：和 CLAUDE.md 内容重复

症状：项目特定的配置写进了 Skill，导致 Skill 无法复用

解决：Skill 只放通用能力，项目配置放 CLAUDE.md

八、实战：创建你的第一个 Skill

步骤 1：创建目录

mkdir -p ~/.claude/skills/my-first-skill

步骤 2：编写 SKILL.md

---
name: my-first-skill
description: |
  Describe what this skill does and when to use it.
  Use when user asks for [specific trigger words].
---

# My First Skill

## Task Definition
What problem does this skill solve?

## Workflow
1. Step one
2. Step two
3. Step three

## Output Format
Describe the expected output structure.

## Rules
- Don't do X
- Always do Y
- Never do Z

## Examples

### Example 1: Basic case
Input: ...
Output: ...

### Example 2: Edge case
Input: ...
Output: ...

步骤 3：测试 Skill

• 自动触发：输入触发词，看 Claude 是否自动加载
• 手动调用：输入 /my-first-skill 直接调用

步骤 4：迭代优化

• 根据使用效果调整 Description
• 补充更多示例
• 细化规则和限制

九、总结

Skill 是 Claude Code 最强大的扩展机制，它让 Claude 拥有了「肌肉记忆」——教一次，永远会。

写好 Skill 的核心要点：

• Description 是关键：决定 Skill 何时被加载
• 单一职责：一个 Skill 只做一件事
• 明确三个问题：何时调用、教什么、怎么教
• 提供具体示例：让 Claude 从示例中学习
• 渐进式披露：分层组织信息，节省 token

记住：Skill 是一份操作手册。你的目标是让 Claude 拿到这份手册后，能够稳定、可靠地完成特定任务。

现在，开始编写你的第一个 Skill 吧！

参考资源：

• Anthropic 官方指南：The Complete Guide to Building Skills for Claude
• Claude Code 文档：Claude Code Skills
• Agent Skills 标准：Agent Skills Specification