Claude Code Skills：可复用的 AI 工作流

时效说明：本文内容以 2026 年 3 月为基准。Claude Code Skills 是 Claude Code 的扩展机制，功能仍在持续演进，使用前建议查阅最新文档。

用了一段时间 Claude Code 之后，你可能会发现一个问题：有些操作反复在做——每次提 PR 都要解释代码风格规范，每次 Code Review 都要重复说"按照我们团队的标准来"，每次部署都要手动确认每个步骤。

你需要的是一种机制，让这些反复使用的"工作方式"能被保存下来、随时调用。

Skills（技能）就是这个答案。

1.1 Skills 是什么

Skills 是可以被复用的指令集合，让你能把一套固定的工作方式封装成一个命令，在 Claude Code 中随时调用。

类比一下 Java 世界的概念：如果说普通的 Claude Code 对话相当于每次都写内联代码，那 Skills 就相当于把逻辑封装成了方法——写一次，调用多次，逻辑集中管理。

Skills 遵循 Agent Skills 开放标准，这意味着 Skills 的格式有规范可循，不是 Anthropic 的私有格式。不过 Claude Code 在标准基础上加了一些专有扩展。

几个关键特点：

Skills 不是内置功能，而是你自己创建的扩展。Claude Code 的内置命令（如 /help、/compact）是固定的，Skills 是你定制的。
Skills 本质上是提示词（Prompt），而不是代码。你写的是"如何做"的指令，Claude 读取这些指令后用自己的工具（读文件、执行命令等）来完成任务。
Skills 可以手动调用，也可以被 Claude 自动识别并使用。这一点和普通命令不同，后面会详细讲。

1.2 为什么需要 Skills

在没有 Skills 之前，你的工作流可能是这样的：

code

你：帮我 review 这个 PR，按照我们团队的规范：
    1. 检查变量命名是否符合驼峰命名法
    2. 确认所有公开方法都有 Javadoc
    3. 检查是否有魔法数字
    ... (重复粘贴这段话第 N 次)

这种重复的问题不只是麻烦，更重要的是不一致——每次粘贴的规范可能有细微差异，而且随着规范演进，你需要记住去更新"上次粘贴的那段文字"。

Skills 解决三类问题：

问题一：重复性工作的标准化。 把"每次都要说的话"写进 Skill，保持一致性，一次修改全局生效。

问题二：复杂工作流的封装。 有些任务需要多个步骤，比如"创建新的微服务模块"可能需要建目录、生成模板文件、注册到配置文件、创建测试目录……把这些步骤写进 Skill，一个命令完成。

问题三：团队知识的沉淀。 Skills 可以放在项目目录下（.claude/skills/），提交到 Git，让整个团队共享同一套工作流。新来的同事克隆仓库，立刻就能用上团队积累的 Skills。

1.3 创建第一个 Skill

1.3.1 目录结构

每个 Skill 是一个目录，核心是一个 SKILL.md 文件：

code

~/.claude/skills/code-review/
├── SKILL.md           # 必须有——主指令文件
├── standards.md       # 可选——详细规范文档
├── examples.md        # 可选——示例
└── scripts/
    └── check.sh       # 可选——辅助脚本

Skill 存放位置有两种：

~/.claude/skills/：个人全局 Skill，所有项目都能用
.claude/skills/（项目根目录）：项目级 Skill，只在当前项目生效

项目级 Skill 优先级低于个人全局 Skill，但当两者都存在时，项目级 Skill 会覆盖同名的全局 Skill（相当于方法重写）。

1.3.2 SKILL.md 的结构

SKILL.md 由两部分组成：YAML frontmatter（配置区） 和 Markdown 正文（指令区）：

yaml

---
# ---- 配置区（YAML 格式）----
name: code-review
description: 按照团队规范进行 Java 代码审查。当用户提到 code review、代码审查、审查代码时使用。
---

# ---- 指令区（Markdown 格式）----
## 代码审查标准

按照以下顺序审查代码：

### 1. 命名规范
- 变量和方法使用驼峰命名法（camelCase）
- 类名使用大驼峰命名法（PascalCase）
- 常量全大写加下划线（UPPER_SNAKE_CASE）

### 2. 注释规范
- 所有 public 方法必须有 Javadoc
- 复杂的业务逻辑必须有内联注释说明"为什么这么做"

### 3. 代码质量
- 不允许出现魔法数字，必须定义为常量
- 方法长度不超过 50 行
- 圈复杂度不超过 10

审查结束后，给出优先级分类：
- **必须修改（P0）**：影响功能正确性或安全性
- **建议修改（P1）**：影响可维护性
- **可选优化（P2）**：风格和性能改进

这就是一个可以工作的 Skill。使用时输入 /code-review，Claude 会读取这些指令，然后按照规范审查你当前工作区的代码。

1.3.3 description 字段的重要性

description 是 Skill 中最容易被忽视但最重要的字段。它决定了Claude 能否在合适的时机自动使用这个 Skill。

Claude Code 会把所有 Skill 的 description 加载到上下文中（总预算约 16,000 字符）。当你提出请求时，Claude 会匹配 description，决定是否自动加载某个 Skill 的完整指令。

好的 description 写法：

yaml

# 好：具体说明触发场景
description: 按照团队规范进行 Java 代码审查。当用户提到 code review、
             代码审查、审查代码、review PR 时使用。

yaml

# 差：太模糊，Claude 不知道什么时候用
description: 代码审查工具

1.4 触发机制：手动调用与自动调用

1.4.1 手动调用

在 Claude Code 中直接输入斜杠命令：

bash

/code-review
/fix-issue 123
/deploy production

斜杠后面的名字对应 Skill 的 name 字段（或者目录名，如果没有配置 name）。

1.4.2 自动调用

当 disable-model-invocation 没有设置为 true 时，Claude 会在判断你的请求匹配某个 Skill 的 description 时，自动加载并使用该 Skill。

举个例子：你有一个 code-review Skill，description 里写了"当用户提到 code review 时使用"。那么你输入：

code

帮我看看这段代码

Claude 可能不会触发。但如果你输入：

code

帮我做一下 code review

Claude 会自动加载 code-review Skill 的完整指令，然后按照你定义的规范来审查。

1.4.3 控制调用方式

通过 frontmatter 可以精细控制谁能调用这个 Skill：

只允许你手动调用（适合有副作用的操作，如部署）：

yaml

---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true  # Claude 无法自动触发这个 Skill
---

部署步骤：
1. 确认当前分支是 main
2. 运行测试套件
3. 构建 Docker 镜像
4. 推送到镜像仓库
5. 触发 Kubernetes 滚动更新
6. 验证健康检查通过

设置 disable-model-invocation: true 后：

你输入 /deploy → 正常工作
Claude 自动建议使用 → 不会发生
description 不会被加载到上下文（Claude 根本不知道这个 Skill 存在）

只允许 Claude 自动调用（背景知识型 Skill）：

yaml

---
name: legacy-payment-context
description: 遗留支付系统的架构背景知识，当讨论支付模块代码时自动加载
user-invocable: false  # 不出现在 / 菜单中
---

## 遗留支付系统背景

这个支付系统建于 2015 年，使用了以下架构决策：
- 使用数据库轮询而不是消息队列（历史原因：当时 MQ 组件不稳定）
- 订单状态机有 7 个状态，其中 `PENDING_RECONCILE` 是特有状态，表示...

这种 Skill 相当于给 Claude 注入"项目历史背景"，每当讨论到支付相关代码，Claude 都会自动知晓这些背景，而不需要你每次手动提供。

1.5 进阶用法

1.5.1 参数传递

Skill 可以接受动态参数。用 $ARGUMENTS 接收全部参数，或者用 $0、$1 接收具体位置的参数：

yaml

---
name: fix-issue
description: 修复指定的 GitHub issue
disable-model-invocation: true  # 需要显式指定 issue 号，不自动触发
argument-hint: "[issue-number]"  # 在自动补全中显示参数提示
---

请修复 GitHub issue #$ARGUMENTS，要求：

1. 阅读 issue 描述，理解需求
2. 定位到相关代码文件
3. 实现修复方案
4. 编写对应的单元测试
5. 创建提交，提交信息格式：`fix: 解决 issue #$ARGUMENTS - <简要描述>`

注意：修复前先确认 issue 是否已经有对应的 PR，避免重复工作。

使用方式：

bash

/fix-issue 123
# Claude 看到的指令是：请修复 GitHub issue #123，要求：...

多参数场景：

yaml

---
name: create-service
description: 创建新的 Spring Boot 微服务模块
argument-hint: "[service-name] [port]"
---

创建名为 $0 的微服务，端口 $1。

步骤：
1. 创建目录 `services/$0/`
2. 生成 pom.xml，设置服务名为 $0
3. 创建主类 `$0Application.java`
4. 在 application.yml 中设置端口为 $1
5. 创建基础的健康检查 Controller

调用方式：

bash

/create-service user-service 8081

1.5.2 动态注入上下文

Skill 中可以用 ! 前缀执行 shell 命令，命令输出会在 Claude 读取指令之前被替换进去：

yaml

---
name: pr-review
description: 审查当前 PR 的代码变更
context: fork  # 在独立的子 agent 上下文中运行（后面会解释）
allowed-tools: Bash(gh *)  # 只允许使用 gh 命令相关的 Bash 操作
---

## 当前 PR 信息

PR 标题和描述：
!`gh pr view`

代码变更内容：
!`gh pr diff`

变更文件列表：
!`gh pr diff --name-only`

## 你的任务

基于以上信息，进行代码审查，重点关注：
1. 是否有潜在的 Bug
2. 是否有性能隐患
3. 是否符合我们的代码规范
4. 是否缺少测试覆盖

! 命令在 Claude 收到指令之前就已经执行完毕——Claude 看到的是命令的输出结果，而不是命令本身。这样 Skill 每次运行时都能获取最新的动态数据（当前 PR 的 diff、当前 Git 状态等）。

1.5.3 子 Agent 隔离运行

context: fork 让 Skill 在一个独立的子 Agent 上下文中运行，与主对话隔离：

yaml

---
name: deep-research
description: 深度分析指定模块的代码质量和架构问题
context: fork    # 在独立子 agent 中运行，不影响主对话上下文
agent: Explore   # 使用专注于探索分析的 agent 类型
---

深度分析 $ARGUMENTS 模块，要求：

1. 用 Glob 找到所有相关文件
2. 逐一阅读核心文件，理解架构设计
3. 识别以下问题：
   - 循环依赖
   - God Class（承担过多职责的类）
   - 重复代码片段
4. 生成报告，包含文件路径引用

子 Agent 隔离有两个好处：

好处一：不污染主对话。 深度研究任务可能需要读几十个文件，这些内容不需要出现在你的主对话上下文里。

好处二：更专注。 子 Agent 只知道当前任务，不会受到主对话中其他讨论的干扰。

注意：子 Agent 只能看到它被分配的任务，看不到你之前的完整对话历史。

1.5.4 工具权限控制

allowed-tools 让你限制 Skill 能使用哪些工具，不在列表里的工具使用时会触发权限确认：

yaml

---
name: code-search
description: 在代码库中搜索特定模式
allowed-tools: Read, Grep, Glob  # 只读操作，不允许写文件或执行命令
---

搜索 $ARGUMENTS 相关的代码，列出：
1. 所有定义位置（类定义、方法定义）
2. 所有调用位置
3. 相关的测试文件

这在团队场景下特别有用：只读的 Skill 可以放心在任何项目上运行，不会意外修改文件。

1.6 最佳实践

1.6.1 Skill 的粒度：单一职责

每个 Skill 做一件事，做好一件事。把"代码审查"和"自动修复"放在同一个 Skill 里，会让指令变得复杂且难以维护。

code

# 好的设计：职责清晰
code-review.md     → 只负责审查，输出问题列表
fix-review.md      → 读取问题列表，执行修复

# 差的设计：职责混乱
code-review-and-fix.md → 审查 + 修复 + 提交，逻辑耦合

1.6.2 description 要精确，避免误触发

description 太宽泛会导致 Claude 在不该用 Skill 的时候自动使用它。加上明确的触发条件：

yaml

# 好：说明具体触发词和使用场景
description: 执行 Java 单元测试并生成覆盖率报告。仅当用户明确要求
             "跑测试"、"执行单元测试"或"生成覆盖率报告"时使用。
             不用于查看测试代码或解释测试逻辑。

# 差：太宽泛
description: 测试相关操作

1.6.3 有副作用的操作一律加 disable-model-invocation

任何会修改文件、执行命令、发起网络请求的 Skill，都应该设置 disable-model-invocation: true，确保只有你显式调用时才会执行：

yaml

---
name: db-migrate
description: 执行数据库迁移脚本
disable-model-invocation: true  # 数据库操作绝对不能自动触发
---

1.6.4 项目级 Skill 提交到 Git

把项目相关的 Skills 放在 .claude/skills/ 目录并提交：

bash

.claude/
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── deploy/
    │   └── SKILL.md
    └── legacy-context/
        └── SKILL.md

这样做的好处：

团队共享同一套工作流，减少沟通成本
Skills 的修改有版本历史，可以追溯
新成员上手即用，不需要口口相传规范

1.6.5 个人 Skill vs 项目 Skill 的分工

类型	路径	适合内容
个人全局	`~/.claude/skills/`	通用技术偏好（代码风格、解释习惯）
项目级	`.claude/skills/`	项目特有规范、业务背景知识、部署流程

技术通用的放个人目录，业务特有的放项目目录——这和 Git 全局配置（~/.gitconfig）与项目配置（.gitconfig）的分工逻辑完全一致。

1.7 一个完整的团队实战案例

假设你在维护一个 Java 微服务项目，可以这样组织 Skills：

.claude/skills/pr-review/SKILL.md——自动触发的 PR 审查：

yaml

---
name: pr-review
description: 审查 PR 变更。当用户说"review PR"、"看一下 PR"、"审查这个 PR"时使用。
context: fork
allowed-tools: Bash(gh *), Read, Grep
---

## PR 基本信息
!`gh pr view`

## 变更文件列表
!`gh pr diff --name-only`

## 完整 diff
!`gh pr diff`

---

按照以下标准进行审查：

**功能正确性（P0）**
- 边界条件是否处理（null、空集合、负数）
- 并发场景是否考虑（共享状态、锁范围）

**代码规范（P1）**
- 公开方法是否有 Javadoc
- 是否有魔法数字
- 异常是否被正确处理（不允许空 catch 块）

**测试覆盖（P1）**
- 新增代码是否有对应的单元测试
- 是否包含边界条件测试

以结构化格式输出，分 P0/P1/P2 三级列出发现的问题，每个问题注明文件名和行号。

.claude/skills/legacy-context/SKILL.md——自动注入的背景知识：

yaml

---
name: legacy-context
description: 遗留系统背景知识。当讨论订单模块、支付流程、用户认证模块时自动加载。
user-invocable: false  # 不需要手动调用，Claude 自动注入
---

## 遗留系统关键背景

**订单状态机**：共 9 个状态，其中 `PENDING_RECONCILE` 和 `MANUAL_REVIEW` 是
本系统特有状态，文档在 `docs/order-state-machine.md`。

**支付模块**：2016 年遗留代码，使用数据库轮询而不是消息队列（历史原因），
改造成本高，暂时不动。相关代码在 `payment-service/src/legacy/`。

**认证模块**：正在从 JWT 迁移到 OAuth2，目前两套并存，
`AuthService` 和 `NewAuthService` 各负责一部分场景。

有了这两个 Skills，团队成员每次讨论遗留代码时，Claude 自动了解背景；需要 review PR 时，一句话触发，输出格式统一。

1.8 小结

Skills 的核心价值是把"临时的口头指令"变成"持久的可复用工作流"。

从技术本质看，Skills 是提示词模板（Prompt Template）+ 触发条件配置 + 可选的运行环境隔离。理解这三点，你就理解了 Skills 的全部。

从使用角度看，Skills 的最大价值在于团队共享：把项目规范、背景知识、标准流程封装成 Skills，提交到 Git，让整个团队共享同一套 AI 工作方式——这才是 Claude Code 在团队协作场景下的真正竞争力所在。