Claude Code 进阶篇（一）：Skills 技能系统详解

---

修订记录

编号	版本	修订人	修订内容	日期
001	1.0	lixh	创建全文	2026-01-19

---

1. 概述

Skills（技能）是 Claude Code 的核心扩展机制，允许你定义特定任务的执行规范、输出格式和工作流程。通过技能系统，你可以让 Claude 按照预设的模板和规则完成复杂任务。

1.1 技能的价值

优势	说明
一致性	每次执行相同任务时，输出格式保持一致
效率	无需重复描述需求，一键触发复杂流程
可复用	团队共享技能，统一工作标准
可定制	根据项目需求创建专属技能

---

2. Skills 工作原理

2.1 核心原理

Skills 的本质是 Prompt 模板注入。当触发一个技能时，Claude Code 会：

2.2 技术实现

从技术角度看，Skills 利用了以下机制：

机制	说明
文件读取	使用 Read 工具读取 .md 技能文件
上下文注入	将技能内容插入当前对话上下文
Prompt Engineering	技能文件本质是结构化的提示词
模板替换	支持变量和参数替换

2.3 为什么用 Markdown

技能文件使用 Markdown 格式的原因：

1. 可读性：人类和 AI 都能轻松理解
2. 结构化：标题、列表、表格提供清晰结构
3. 灵活性：可包含代码块、示例等丰富内容
4. 版本控制：作为文本文件便于 Git 管理

2.4 与 System Prompt 的关系

---

3. 技能的类型

2.1 内置技能

Claude Code 提供了一些开箱即用的技能：

技能	触发方式	功能
commit	/commit	生成符合规范的 Git 提交
review-pr	/review-pr	审查 Pull Request
save	/save	保存上下文到记忆系统
remember	/remember	查找相关记忆

2.2 自定义技能

通过在项目中创建技能文件，你可以定义专属技能：

项目根目录/
└── .claude/
    └── skills/
        ├── design/
        │   ├── high-level-design.md
        │   └── api-design.md
        ├── testing/
        │   └── test-plan.md
        └── tools/
            └── md-output.md

---

3. 技能文件结构

3.1 文件位置

技能文件存放在项目的 .claude/skills/ 目录下：

.claude/
└── skills/
    └── [category]/
        └── [skill-name].md

3.2 文件格式

每个技能文件是一个 Markdown 文档，包含以下结构：

# Skill: [技能名称]

## 描述

[简要说明技能用途]

## 触发条件

- [触发条件1]
- [触发条件2]

## 执行规则

### 1. [规则类别1]
[具体规则说明]

### 2. [规则类别2]
[具体规则说明]

## 输出模板

[可选：定义输出的标准格式]

## 示例

[可选：提供使用示例]

---

4. 创建自定义技能

4.1 示例：创建代码审查技能

文件路径： .claude/skills/review/code-review.md

# Skill: Code Review

## 描述

对代码进行全面审查，检查代码质量、安全性和最佳实践。

## 触发条件

- 用户请求代码审查
- 用户提及 `/code-review`
- 用户说 "审查代码"、"review code"

## 执行规则

### 1. 审查维度

按以下维度检查代码：

| 维度 | 检查内容 |
|------|---------|
| 功能正确性 | 逻辑是否正确、边界条件处理 |
| 代码风格 | 命名规范、代码格式、注释质量 |
| 性能 | 时间复杂度、空间复杂度、资源使用 |
| 安全性 | 注入风险、敏感信息处理 |
| 可维护性 | 代码结构、函数拆分、复用性 |

### 2. 输出格式

使用结构化格式输出审查结果：

1. **概述**：整体评价（1-2句话）
2. **问题列表**：按严重程度排序
3. **改进建议**：具体的优化方案
4. **示例代码**：修改后的代码示例

### 3. 严重程度分级

| 级别 | 标识 | 说明 |
|------|------|------|
| 严重 | 🔴 | 必须修复，影响功能或安全 |
| 警告 | 🟡 | 建议修复，影响可维护性 |
| 提示 | 🟢 | 可选优化，提升代码质量 |

## 示例输出

### 概述
这段代码实现了基本功能，但存在 2 个严重问题和 3 个警告级别问题。

### 问题列表

🔴 **严重：SQL 注入风险** (第 15 行)
- 问题：直接拼接用户输入到 SQL 语句
- 建议：使用参数化查询

🟡 **警告：函数过长** (第 20-80 行)
- 问题：单个函数超过 60 行
- 建议：拆分为多个职责单一的小函数

### 改进建议

1. 引入 ORM 或参数化查询
2. 将数据处理逻辑抽取为独立函数
3. 添加输入验证

4.2 示例：创建文档生成技能

文件路径： .claude/skills/docs/api-doc.md

# Skill: API Documentation

## 描述

根据代码自动生成 API 接口文档。

## 触发条件

- 用户请求生成 API 文档
- 用户提及 `/api-doc`
- 用户说 "接口文档"、"API 文档"

## 执行规则

### 1. 分析步骤

1. 扫描项目中的路由/控制器文件
2. 提取所有 API 端点
3. 分析请求参数和响应格式
4. 生成结构化文档

### 2. 文档结构

为每个接口生成以下信息：

| 字段 | 说明 |
|------|------|
| 接口名称 | 接口的功能描述 |
| 请求方法 | GET/POST/PUT/DELETE |
| 请求路径 | API 端点路径 |
| 请求参数 | 参数名、类型、必填、说明 |
| 响应格式 | 响应体结构和示例 |
| 错误码 | 可能的错误响应 |

## 输出模板

### [接口名称]

**基本信息**

| 属性 | 值 |
|------|---|
| 方法 | `[METHOD]` |
| 路径 | `[PATH]` |
| 认证 | [是否需要认证] |

**请求参数**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ... | ... | ... | ... |

**响应示例**

```json
{
  "code": 200,
  "data": { ... }
}

---

## 5. 技能触发方式

### 5.1 显式触发（斜杠命令）

使用 `/` 加技能名称直接调用：

/commit
/code-review
/api-doc

### 5.2 隐式触发（关键词匹配）

在 `CLAUDE.md` 中配置自动触发规则后，输入特定关键词会自动激活技能：

```markdown
## Auto-Trigger Rules

| Keywords | Skill | Action |
|----------|-------|--------|
| 代码审查、review | `/code-review` | 读取技能文件并执行 |
| API文档、接口文档 | `/api-doc` | 读取技能文件并执行 |

用户输入示例：

> 帮我做个代码审查
(自动触发 /code-review 技能)

---

6. 技能的高级特性

6.1 技能参数

技能可以接受参数：

> /code-review src/auth.js

> /api-doc --format=openapi

在技能文件中定义参数处理：

## 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| file | string | 全部 | 要审查的文件路径 |
| format | string | markdown | 输出格式 |

6.2 技能组合

复杂任务可以组合多个技能：

## 执行步骤

1. 调用 `/code-review` 检查代码质量
2. 调用 `/test-plan` 生成测试方案
3. 调用 `/api-doc` 更新接口文档

6.3 技能继承

可以创建基础技能，让其他技能继承：

# Skill: Extended Review

## 继承

基于 `/code-review` 技能扩展。

## 额外规则

除基础审查外，额外检查：
- 单元测试覆盖率
- 文档完整性

---

7. 技能最佳实践

7.1 命名规范

类别	建议
文件名	使用小写字母和连字符：api-design.md
技能名	简洁明了：/commit、/review
目录	按功能分类：design/、testing/、tools/

7.2 内容规范

1. 描述清晰：明确技能的用途和适用场景
2. 规则具体：避免模糊的描述，给出具体指导
3. 示例完整：提供完整的输入/输出示例
4. 格式统一：保持所有技能文件的结构一致

7.3 维护建议

## 修订记录

| 版本 | 日期 | 修改内容 |
|------|------|---------|
| 1.0 | 2026-01-01 | 初始版本 |
| 1.1 | 2026-01-15 | 增加安全检查规则 |

---

8. 常见技能模板

8.1 设计文档类

.claude/skills/design/
├── high-level-design.md    # 概要设计
├── detailed-design.md      # 详细设计
├── database-design.md      # 数据库设计
└── api-design.md           # 接口设计

8.2 测试类

.claude/skills/testing/
├── test-plan.md            # 测试方案
├── test-report.md          # 测试报告
└── test-case.md            # 测试用例

8.3 工具类

.claude/skills/tools/
├── md-output.md            # Markdown 输出规范
├── code-template.md        # 代码模板
└── commit-message.md       # 提交信息规范

8.4 从实际工作中提炼 Skill

以上这些技能模板都是基于真实工作场景提炼而来的。在日常开发中，我们经常遇到这些痛点：

痛点	传统方式	Skill 方式
重复的文档工作	每次手动编写，格式不一致	定义文档模板 Skill，一键生成
Markdown 格式问题	反复返工修改编号、格式	/md-output 统一输出规范
架构图/流程图绘制	手动调整样式，风格不统一	/drawio 定义绘图规范
设计文档编写	每次从零开始，容易遗漏	/api-design 等标准化输出

提炼 Skill 的思路：

1. 识别重复工作：哪些任务你每周都在做？
2. 总结规范：这些任务有没有固定的格式或流程？
3. 抽象模板：把规范写成 Skill 文件
4. 持续优化：根据使用反馈不断完善

示例：从 Markdown 返工中诞生的 /md-output

# 问题：每次生成文档，编号格式都不一致
#      H2 有时编号有时不编号，返工重写

# 解决：提炼为 Skill
.claude/skills/tools/md-output.md

# 效果：
# - H2 统一使用 "## 1. 标题" 格式
# - 特殊章节（修订记录、参考资料）不编号
# - 每次输出格式一致，无需返工

熟练提炼这些公共的、常用的技能，能够极大提升工作效率。把你的经验固化为 Skill，让 AI 按照你的标准工作。

9. 调试技能

9.1 验证技能加载

> 读取 .claude/skills/review/code-review.md

(Claude 会显示文件内容，确认文件存在且格式正确)

9.2 检查触发规则

> 我说"代码审查"会触发什么技能？

(Claude 会说明匹配的技能和执行逻辑)

9.3 手动测试

> 使用 /code-review 技能审查 src/main.js

(观察输出是否符合技能定义的格式)

---

10. 下一步

了解了 Skills 系统后，继续深入学习：

• 04-Agent代理模式深度解析：学习如何使用 Agent 处理复杂任务
• 08-CLAUDE.md配置最佳实践：将技能整合到项目配置中

---

参考资料

• Claude Code Skills 官方文档
• 示例技能库