给 Claude Code 装技能包：Skills 实战

CLAUDE.md 越写越长，每轮都在烧 token 背课文。Skills 按需加载：启动只占 100 token，调用时才读全文。从零搭 3 个 Java 实战 Skill（TDD 引导、重构检查、智能拆 commit），加子代理编排和踩坑清单。

我的 CLAUDE.md 曾经写到 400 多行。

项目规范、代码风格、Maven 构建约定、接口设计准则、异常处理模板......能想到的全往里塞。那感觉就像装修时把所有家具挤进一间卧室------满当当，但住不了人。

直到有一天我盯着 Claude Code 的 token 计数器发现：每次对话开始，光加载 CLAUDE.md 就烧掉快 5000 token。这意味着我的 200K 上下文窗口，还没开口就少了 2.5%。换算成钱，如果我每天跟 Claude 对话 50 轮，一个月下来光"背课文"就烧了约 7500K token------纯纯的知识税。

更讽刺的是，400 行规则里有 80% 在当前任务中根本用不上。我写接口的时候不需要看异常处理模板，调 SQL 的时候不需要读前端组件规范。但 Claude 不管------它每轮都老老实实全文背诵，一视同仁。

然后我发现了 Skills。

Skills 是什么：CLAUDE.md 的"减负手术"

一句话：Skill 是独立的 Markdown 文件，有自己的 YAML 元数据头，Claude 启动时只读"门牌号"（约 100 token），任务匹配时才加载全文。

打个比方------CLAUDE.md 是公司员工手册，每个人入职第一天就得全文背诵；Skill 是各岗位的 SOP 手册，放在工位抽屉里，需要时才翻开。你不会把保洁阿姨的清洁流程写进公司章程吧？

来看一张对比表，直观感受区别：

维度	CLAUDE.md	SKILL.md
加载方式	每轮都注入，始终消耗 token	启动读 100 token 元数据，匹配时才读全文
上下文压缩时	永远保留	body 可能被摘要
适合放什么	全局不变的项目约定（10-20 条）	具体工作流、检查清单、操作步骤
建议体量	< 100 行	想多详细就多详细

还有个三角关系需要理清：

MCP --- 给 Claude 接入外部工具/API（"能力"）
Skill --- 教 Claude 什么时候、怎么用这些能力（"方法论"）
Hook --- 不管 Claude 怎么想，强制在特定事件时执行动作（"护栏"）

三者组合才是完整体系：MCP 提供锤子 → Skill 教在哪儿钉钉子 → Hook 确保不会砸到自己手。

5 分钟上手：用 skill-creator 生成你的第一个 Skill

看到这里你可能觉得：YAML 元数据、目录结构、description 公式......这也太劝退了。

好消息是------你根本不用手写。Claude Code 内置了 /skill-creator，你只需要用人话描述"我想要一个什么样的技能"，它帮你把 SKILL.md 连目录一起生成好。

实操：我要一个 API Review 技能

打开 Claude Code，输入：

bash 复制代码

/skill-creator

它会问你想要什么。我这么描述的：

帮我做一个 API review 的 skill。针对 Java Spring Boot 的 REST Controller，检查 URL 命名规范（kebab-case）、HTTP 方法语义、响应结构是否统一包装、参数校验注解、异常处理。只允许用 mvn 命令、grep 和读文件，不能改代码。

30 秒不到，它生成了完整的 .claude/skills/api-review/SKILL.md：

markdown 复制代码

---
name: api-review
description: "Review a Java Spring Boot REST API for common issues: naming conventions, HTTP method usage, response structure, error handling, parameter validation. Use when reviewing or writing a new controller."
allowed-tools:
  - Bash(mvn:*)
  - Bash(grep:*)
  - Read
---

## API Review 检查清单

对目标 Controller 执行以下检查，逐项报告结果：

### 命名规范
- URL 路径是否 kebab-case（`/user-orders` 而非 `/userOrders`）
- 方法名是否体现动作（`createOrder` 而非 `order`）

### HTTP 语义
- GET 是否幂等且无副作用
- POST/PUT 区分是否正确（创建 vs 全量更新）
- DELETE 是否返回 204 No Content

### 响应结构
- 成功响应是否统一包装（`ResponseEntity<Result<T>>`）
- 分页接口是否包含 total/pageSize/currentPage
- 错误响应是否有 errorCode + message

### 参数校验
- @RequestBody 是否配合 @Valid
- 路径参数是否有类型约束
- 必填参数是否标注 @NotNull/@NotBlank

### 异常处理
- 是否有 @ControllerAdvice 统一兜底
- 业务异常是否抛自定义 Exception 而非 RuntimeException

目录结构、YAML frontmatter、description 措辞------全都不用操心。你要做的就是看一眼生成结果，觉得哪里不对再微调。

我微调了什么

skill-creator 生成的初版已经 90% 能用了，我只动了两处：

description 加了触发词：原版是通用描述，我追加了 "Use when reviewing or writing a new controller" 这半句。因为我发现没这句的话，Claude 在我说"帮我看看这个 Controller"时不一定触发。
加了分页接口的检查项：我项目里有自己的分页规范，skill-creator 不知道，手动补上就行。

调用

bash 复制代码

/api-review src/main/java/com/example/controller/OrderController.java

Claude 匹配到 skill name，加载完整 body，拿着检查清单去审代码。allowed-tools 限制它只能用 Maven 命令、grep 和读文件------想删文件？没门。

整个过程：描述需求 30 秒 + 生成 30 秒 + 微调 2 分钟 = 3 分钟搞定一个专业级 Skill。 手写 YAML？那是上个版本的玩法了。

我给 Java 项目做的 3 个 Skills

一个 demo 不过瘾。以下三个是我实际在用的，全都是 /skill-creator 生成后微调出来的。我会重点说"我怎么描述需求"和"生成后我改了什么"------因为这才是你真正需要学的。

Skill 1：`/tdd` --- 测试驱动开发引导

我对 skill-creator 说的话：

我要一个 TDD 引导的 skill。输入一个类名或功能描述，帮我生成 JUnit 5 测试骨架。方法名用 should_xx_when_xx 格式，加 @DisplayName 中文描述。只写测试骨架不写实现，每个方法体标 TODO。不 mock 数据库，我们用 Testcontainers。能编译就行，不用跑通。只允许 mvn compile、mvn test、读写文件。

生成后我微调了什么：

补了"覆盖场景分析"步骤------让它在生成代码前先列出 happy path / 边界 / 异常三类场景，我确认后再写。原版直接开写，有时漏场景。
加了输出格式要求------除了生成文件，还要给我一个"覆盖场景清单 + 建议实现顺序"。

最终效果：

markdown 复制代码

---
name: tdd
description: "Generate JUnit 5 test skeleton for a given class or feature. Creates test class with descriptive method names following Given-When-Then pattern. Use before implementing new features or fixing bugs."
allowed-tools:
  - Bash(mvn test:*)
  - Bash(mvn compile:*)
  - Read
  - Write
  - Edit
argument-hint: [target_class_or_feature]
---

## TDD 工作流

### 输入
目标：$ARGUMENTS

### 步骤

1. 读取目标类（如已存在）或需求描述
2. 分析需要覆盖的场景：
   - 正常路径（happy path）
   - 边界条件（空值、极值、重复）
   - 异常路径（非法参数、依赖失败）
3. 生成测试类骨架：
   - 类名：`{TargetClass}Test`
   - 方法命名：`should_{expectedBehavior}_when_{condition}`
   - 每个方法只写注释描述意图，方法体标注 `// TODO: implement`
   - 使用 @DisplayName 写中文描述
4. 将测试文件写入对应的 test 目录
5. 运行 `mvn compile -pl {module}` 确认编译通过

### 约束
- 不写实现代码，只写测试骨架
- 不 mock 数据库（项目用 Testcontainers 做集成测试）
- 每个测试方法独立，无顺序依赖

### 输出
- 测试文件路径
- 覆盖场景清单（列表形式）
- 建议的实现顺序

实际体感：以前我写测试是"写完功能补测试"（伪 TDD），现在是真正的"测试先行"。Claude 生成的测试骨架逼我先想清楚边界条件，反而让实现阶段更顺畅。

Skill 2：`/refactor-check` --- 重构安全检查

我对 skill-creator 说的话：

做一个重构安全检查 skill。我重构完代码后跑一遍，帮我检查：public 方法签名有没有改变、下游有没有调用方没更新、测试能不能通过、序列化字段和数据库实体有没有兼容问题。用 fork 模式跑，不要污染主会话。只读不改，给我一个通过/关注/阻塞的分类报告。

生成后我微调了什么：

加了动态上下文注入 !git diff --stat 和 `!`git log -n 5 --oneline------让子代理启动时就知道改了哪些文件，省去自己跑 git 的一轮交互。
把 agent 类型从默认改成 Explore------探索型代理更擅长快速搜索和阅读代码片段，比通用型快。
补了"向后兼容"检查项里的 RPC 接口部分------我项目里有 Protobuf 接口，skill-creator 不了解这个上下文。

最终效果：

markdown 复制代码

---
name: refactor-check
description: "Safety check after refactoring Java code. Verifies API compatibility, test coverage, and behavioral equivalence. Use after any structural code change: extract method, rename, move class, change signature."
context: fork
agent: Explore
allowed-tools:
  - Bash(mvn:*)
  - Bash(grep:*)
  - Bash(git diff:*)
  - Bash(git log:*)
  - Read
---

## 重构安全检查

### 上下文
- 当前分支变更：!`git diff --stat`
- 最近提交：!`git log -n 5 --oneline`

### 检查项

#### 1. 接口签名兼容性
- 对比变更前后的 public 方法签名
- 检查是否有下游调用方（grep 方法名）
- 如果签名变了：有没有 @Deprecated 过渡？调用方是否同步更新？

#### 2. 行为等价性
- 重构前后的逻辑是否等价（特别注意：null 处理、异常抛出、返回值语义）
- 是否引入了新的副作用（日志、缓存、事件发布）

#### 3. 测试覆盖
- 被改动的类是否有对应测试？
- 测试是否通过？执行 `mvn test -pl {module} -Dtest={TestClass}`
- 如果没有测试：标红警告

#### 4. 向后兼容
- 是否涉及序列化的类（JSON/Protobuf）？字段改名会破坏兼容
- 是否涉及数据库实体？字段变更需要 migration
- 是否涉及 RPC 接口？需要确认调用方版本

### 输出格式
- ✅ 通过项
- ⚠️ 需关注（不阻塞但要人工确认）
- ❌ 阻塞项（必须修复才能合入）

实际体感 ：以前重构完直接提 PR，等 review 时被指出"下游没改"。现在跑一遍 /refactor-check，阻塞项本地就暴露。有次它抓到一个 Protobuf 字段重命名的兼容问题------上线了下游反序列化直接炸。

Skill 3：`/commit-split` --- 语义化拆分提交

我对 skill-creator 说的话：

做一个拆分 commit 的 skill。分析我当前的 staged 和 unstaged 变更，按逻辑关系拆成多个原子 commit。先出方案让我确认，我说 go 再执行。绝对不 push，只做本地 commit。不能改代码内容。只给 git 和读文件权限。加上 disable-model-invocation，别让 Claude 自己触发。

生成后我微调了什么：

加了 argument-hint: [optional_commit_style: conventional|simple]------让我可以指定 commit message 风格。
补了提交顺序规则"基础设施/依赖 → 核心逻辑 → 测试 → 文档"------默认生成的顺序有时不太合理。
加了"如果有 unstaged 变更混在一起，先问我要不要 stash"------避免误操作。

最终效果：

markdown 复制代码

---
name: commit-split
description: "Analyze staged/unstaged changes and split them into semantic git commits. Each commit should be atomic and have a clear purpose. Use when you have multiple unrelated changes mixed together."
disable-model-invocation: true
allowed-tools:
  - Bash(git:*)
  - Read
argument-hint: [optional_commit_style: conventional|simple]
---

## 语义化拆分提交

### 当前变更
!`git diff --stat`
!`git diff --cached --stat`

### 规则

1. **分析变更**：按逻辑关系将文件分组
   - 同一功能的代码 + 测试 = 一个 commit
   - 重构 ≠ 新功能 ≠ bug 修复，不混在一个 commit
   - 配置文件变更单独一个 commit（除非是新功能必需的配置）

2. **生成 commit 计划**：列出拆分方案，每个 commit 包含：
   - 涉及的文件列表
   - commit message（格式：$0 参数指定风格，默认 conventional）
   - 提交顺序（基础设施/依赖 → 核心逻辑 → 测试 → 文档）

3. **等待确认**：输出计划后暂停，等我说"go"再执行

4. **执行**：逐个 `git add` + `git commit`

### 约束
- 绝对不 push，只做本地 commit
- 不修改任何代码内容，只做 stage 和 commit
- 如果有 unstaged 的变更混在一起，先问我要不要 stash 无关部分

实际体感 ：以前拆 commit 纯手工 git add -p，8 个文件拆 3 个 commit 花 10 分钟。现在 /commit-split 出方案 → 扫一眼确认 → 执行，全程 2 分钟。而且它比我更严格------我有时偷懒把测试和代码塞同一个 commit，它不会。

小结：skill-creator 的正确姿势

用了这么多轮，我总结出跟 /skill-creator 对话的模板：

说清楚做什么：不是"帮我 review"，而是"检查 URL 命名、HTTP 方法语义、响应结构......"
说清楚边界：哪些能做哪些不能做，允许用什么工具
说清楚触发时机：什么场景下该用这个 skill
说清楚项目特殊性：用什么框架、有什么约定、哪些是你们独有的规则

skill-creator 生成的初版通常 80-90% 能用。剩下 10-20% 需要你微调的，基本都是"它不知道你项目上下文"的部分------这恰恰是手写不如口述的原因：你用人话把业务需求说清楚，比你去啃 YAML 语法高效十倍。

高级玩法：子代理编排

上面的 /refactor-check 已经用了 context: fork，但那只是单个子代理。Skills 还支持更复杂的编排------一个 skill 预加载其他 skills，让子代理带着"专业知识"上场。

场景：代码审计一条龙

markdown 复制代码

---
name: audit
description: "Comprehensive code audit combining security, performance, and style checks. Spawns a specialized sub-agent that has domain expertise loaded. Use before major releases or PR reviews."
context: fork
agent: general-purpose
skills:
  - security-checklist
  - performance-patterns
  - java-style-guide
allowed-tools:
  - Bash(mvn:*)
  - Bash(grep:*)
  - Bash(find:*)
  - Read
argument-hint: [directory_or_module]
---

## 综合代码审计

对 $ARGUMENTS 执行三维审计：

### 安全维度（参考 security-checklist skill）
- SQL 注入风险
- 硬编码凭证
- 未校验的用户输入
- 不安全的反序列化

### 性能维度（参考 performance-patterns skill）
- N+1 查询
- 缓存未命中的热路径
- 不必要的对象创建（循环内 new）
- 阻塞调用在异步上下文

### 风格维度（参考 java-style-guide skill）
- 方法长度 > 30 行
- 嵌套深度 > 3 层
- 命名不达意的变量

### 输出
按严重程度排序：Critical → Warning → Info
每条发现附带文件路径 + 行号 + 修复建议

这里的 skills: 数组让子代理启动时自动加载另外三个 skill 的知识。相当于你派了个实习生去审代码，但走之前递给他三本参考手册。

子代理在独立上下文中工作，扫完所有文件后把报告递回主会话。主会话的上下文完全不受污染------你可以继续写代码、聊需求，审计结果出来后就像收到一封邮件。

`context: fork` 的适用判断

什么时候该用 fork？我的经验法则：

场景	用 fork？	理由
需要扫描 > 10 个文件	是	避免中间输出吃满主上下文
需要运行多个 grep/find	是	搜索结果是"过程垃圾"，不需要保留
只改一个文件	否	开 fork 的开销不值得
需要跟我交互确认	否	fork 里的子代理没法直接问你问题
有副作用（写文件、git 操作）	看情况	如果副作用需要我确认，别用 fork

踩坑实录

坑 1：description 写太短，Claude 死活不触发

反面教材：

yaml 复制代码

description: "Review API"

这等于告诉 Claude："有个东西能 review API"。问题是 Claude 不知道什么时候该用它------你让它"帮我看看这个 Controller"，它不会联想到这是一次 API review。

正面教材：

yaml 复制代码

description: "Review a Java Spring Boot REST API for common issues: naming conventions, HTTP method usage, response structure, error handling, parameter validation. Use when reviewing or writing a new controller."

公式： $具体做什么$ + $检查哪些方面$ + $什么时候该用$ 。写得越具体，触发越精准。

坑 2：YAML 里写了尖括号

yaml 复制代码

description: "Check if <T> generics are used correctly"  # 炸了

YAML 解析器把 <T> 当 XML 标签了。解决方案：用引号包裹并转义，或者干脆换种表述避开尖括号。

yaml 复制代码

description: "Check if Java generics (type parameters) are used correctly"  # OK

坑 3：忘设 disable-model-invocation，Claude 自动帮我推了代码

我有个 skill 负责"打 tag + push"。某天我跟 Claude 聊到"这个版本差不多了"，它自动触发了这个 skill，一路 tag → push → done。我还没准备好发版呢。

教训：任何有副作用的 skill，必须设 disable-model-invocation: true 。宁可多打一次 /，也别让 AI 自作主张。

坑 4：allowed-tools 给太宽，skill "越权"了

一个只读审查的 skill，我没限制 allowed-tools，结果 Claude 审着审着觉得"这里有 bug 我直接改了吧"------它的出发点是好的，但 review 和 fix 是两个动作，不该混在一起。

原则：skill 的职责是什么，allowed-tools 就给什么。审查类 = Read + grep；生成类 = Read + Write + Edit；执行类 = Bash(特定命令)。

坑 5：skill body 被 auto-compaction 吃掉了

长会话中，Claude 会自动压缩历史以节省上下文。如果你的 skill body 在早期被加载过一次，后面压缩时它可能被摘要或截断。

解决方案：关键步骤写在 body 最前面（压缩时通常保留开头），或者在需要时手动重新 /skill-name 触发一次。

我的 Skills 管理心法

用了两个月，总结几条原则：

1. CLAUDE.md 瘦身到 100 行以内

CLAUDE.md 只放"宪法级"内容：项目技术栈声明、绝对不能违反的规则（比如"不用 Lombok"）、目录结构说明。其余全部下放到 Skills。

我的 CLAUDE.md 从 400 行砍到 67 行。token 消耗从 ~5000 降到 ~1800。每轮省 3200 token，50 轮就是 160K------快够塞一整个中型类的源码了。

2. 项目级 vs 全局级的分配

markdown 复制代码

全局（~/.claude/skills/）：
  - commit-split（所有项目通用）
  - code-review-general（通用审查清单）
  
项目级（.claude/skills/）：
  - tdd（依赖项目测试框架配置）
  - api-review（依赖项目的接口规范）
  - refactor-check（依赖项目的架构约定）

判断标准：如果 skill 里引用了项目特定的路径、框架或约定，就放项目级。如果换个项目也能用，放全局。

3. 一个 Skill 只做一件事

跟 Unix 哲学一样------Do one thing well。别把"生成测试 + 跑测试 + 修复失败"塞进一个 skill。拆成 /tdd（生成） + /test-fix（修复），组合使用比巨型 skill 灵活得多。

4. description 是最重要的一行

我在 description 上花的时间经常比写 body 还多。因为 body 写得再好，Claude 读不到就是废纸。description 是 Skill 的"简历"------100 token 的篇幅里，要让 Claude 能判断"这个任务是否匹配我"。

公式再强调一遍： $做什么$ + $检查/处理哪些方面$ + $什么时候该用它$ 。

5. 定期审计你的 Skills 菜单

bash 复制代码

find .claude/skills -name "SKILL.md" -exec grep -l "name:" {} ;

每个月扫一遍：哪些 skill 上个月一次都没触发？要么是 description 写得烂（改），要么是这个工作流你已经不需要了（删）。死 skill 虽然只占 100 token，但积少成多也是浪费。

从 CLAUDE.md 到 Skills：一次思维转变

用 Skills 之前，我和 Claude 的关系是"我把所有规矩贴墙上，你每次都看一遍"。用了之后变成"规矩在抽屉里按标签分好，需要哪个翻哪个"。

这不只是 token 优化的技术问题，更是一种工程思维：把"始终记住"变成"知道去哪儿找"。人脑这么干叫 GTD，AI 这么干叫 Skills。

与其让 Claude 当全才------每轮对话都带着全部知识上场------不如让它持证上岗：干什么活，加载什么证。轻装上阵，按需武装。

你的 CLAUDE.md 现在几行？如果超过 100 行，是时候给它做个减负手术了。

给 Claude Code 装技能包：Skills 实战

Skills 是什么：CLAUDE.md 的"减负手术"

5 分钟上手：用 skill-creator 生成你的第一个 Skill

实操：我要一个 API Review 技能

我微调了什么

调用

我给 Java 项目做的 3 个 Skills

Skill 1：/tdd --- 测试驱动开发引导

Skill 2：/refactor-check --- 重构安全检查

Skill 3：/commit-split --- 语义化拆分提交

小结：skill-creator 的正确姿势

高级玩法：子代理编排

场景：代码审计一条龙

context: fork 的适用判断

踩坑实录

坑 1：description 写太短，Claude 死活不触发

坑 2：YAML 里写了尖括号

坑 3：忘设 disable-model-invocation，Claude 自动帮我推了代码

坑 4：allowed-tools 给太宽，skill "越权"了

坑 5：skill body 被 auto-compaction 吃掉了

我的 Skills 管理心法

从 CLAUDE.md 到 Skills：一次思维转变

Skill 1：`/tdd` --- 测试驱动开发引导

Skill 2：`/refactor-check` --- 重构安全检查

Skill 3：`/commit-split` --- 语义化拆分提交

`context: fork` 的适用判断