第 03 章

Skills

把"方法论 + 模板"固化为可复用的能力包

一次写好审查标准，以后每次审查都一样稳

输出不稳定

你有没有发现，让 Claude 做同一件事，每次结果都不一样？

代码审查

昨天让它审查代码，它列了 12 条发现，按严重程度排好，结构清晰。今天同一个仓库再审查一次，它换了 5 条完全不同的发现，格式也不一样了。

重构规划

你花了半小时跟 Claude 描述"先分析代码味道，再列重构优先级，最后给实施方案"。结果不错——但下次换个项目，又得重新描述一遍。

团队协作

你总结了一套审查清单，A 同事也总结了一套。两边标准不同，输出格式各异，下游流程根本没法统一消费。

Skill 就是为这个设计的：把一个任务的"怎么做"和"输出长什么样"打包成一个目录。Claude 每次调用都遵循同样的步骤和模板，输出质量稳定可预测。

开始之前

适合谁

经常做代码审查、重构规划、文档生成，希望批量复用高质量输出的人
想把团队经验从"个人脑子里"搬到"可安装的技能包"里的人
已经会写 Slash Command，想让命令更强大的开发者

读完后你应该已经能

说清 Skill 由哪些文件构成、各自职责是什么
创建一个带模板和参考资料的最小 Skill
理解渐进式披露：什么时候该拆分文件
判断"这个需求该做 Skill 还是做 Command"

这些内容暂时先不碰

复杂插件的打包与发布流程
多 agent 编排中的 Skill 分配策略
生产级 Skill 的 scripts 和 assets 设计

Skill 是什么

一句话定义 + 白话 + 一个能跑的例子

Skill是一个目录化的能力单元，包含 SKILL.md（核心说明）、templates（模板）、references（参考资料），可以被 / 触发或由 Claude 自动调用。

说白了，Skill 就是一份"标准操作手册"——你把"按什么步骤做、输出长什么样、要注意什么"全写进去。以后每次触发，Claude 都照着这本手册来，不凭感觉发挥。

它和你上一章学的 Slash Command 有什么区别？Command 是一个入口——你敲 /commit，它就去执行。Skill 是一个能力包——除了入口（SKILL.md），还可以带上模板、参考资料、脚本等配套文件。所有自定义 Slash Command 现在都推荐用 Skill 来做。

判断标准：如果你只需要一段提示词，用 Command 就够了。如果还需要模板、参考资料、或希望 Claude 自动判断何时使用——做 Skill。

渐进式加载

Skill 不是一次性全塞进上下文的——它分三层加载

为什么这样设计：把所有内容一次性塞进上下文，既浪费 token 又降低响应质量。渐进式加载确保 Claude 只带"真正需要的信息"进对话。

加载流程

Claude 从发现到执行，经历四个步骤

1. 扫描目录

遍历 .claude/skills/ 和 ~/.claude/skills/，发现所有 Skill 目录

2. 匹配描述

根据 description 判断与当前任务是否相关，不相关则跳过

3. 读取 SKILL.md

加载核心说明：触发条件、执行步骤、输出格式

4. 按需加载

脚本、模板、参考资料——用到时才读取

为什么分四步而不是一步：如果一次性把所有 Skill 全部加载，上下文会立刻爆炸。四步流程确保 Claude 只带"真正相关的、真正需要的信息"进入对话，既省 token 又提高响应质量。

目录结构

一个 Skill 目录里该放什么

.claude/skills/
└── code-review/               [技能目录]
    ├── SKILL.md               [核心说明 — 必需]
    ├── templates/             [模板 — 可选]
    │   └── finding-template.md
    └── references/            [参考资料 — 可选]
        └── review-checklist.md

文件	职责	什么时候需要
`SKILL.md`	触发条件、执行步骤、输出格式	总是需要
`templates/`	输出骨架、占位符	输出格式复杂时
`references/`	知识库、规范、清单	有行业标准和团队规范时
`scripts/`	辅助脚本	需要自动化预处理时

写好 SKILL.md

一个能跑起来的 SKILL.md 至少包含三块

---
name: code-review
description: 全面审查代码质量、安全性和可维护性
argument-hint: "[focus-area]"
allowed-tools: Read, Grep, Glob
---

# Code Review

## 触发条件
当用户请求代码审查、PR 审查时自动激活。

## 执行步骤
1. 读取变更文件列表
2. 按审查清单逐项检查
3. 按严重程度分类发现
4. 使用 finding-template.md 格式化输出

## 审查维度
- **代码质量**：命名、结构、可读性
- **安全性**：输入验证、权限、敏感数据
- **可维护性**：耦合度、扩展性、测试覆盖

## 输出格式
参考 templates/finding-template.md，每条发现包含：
严重程度、文件路径、行号、问题描述、修复建议

三块不可省略：触发条件（Claude 什么时候该用它）、执行步骤（具体做什么）、输出格式（结果长什么样）。缺了任何一块，输出就会不稳定。

字段	作用	什么时候用
`model`	指定运行 Skill 时使用的模型	需要特定模型能力时（如 Opus 做深度分析）
`user-invocable`	控制用户是否能手动调用此 Skill	内部辅助 Skill 不希望用户直接触发时设为 `false`
`context`	注入额外上下文信息	Skill 执行时需要环境变量或配置信息
`agent`	配置 Skill 在哪个 agent 上下文中运行	需要指定运行环境或角色时
`hooks`	Skill 生命周期钩子（加载前/后等）	需要在 Skill 执行前后自动运行脚本

触发控制三件套：disable-model-invocation: true 阻止 Claude 自动触发，只允许用户手动调用——适合有副作用的操作（如部署、删除）。user-invocable: false 则反过来——允许 Claude 自动用，但不让用户手动触发。allowed-tools 限制 Skill 只能使用指定工具，缩小权限范围，降低风险。

模板与参考

什么时候该拆成独立文件，而不是全写在 SKILL.md 里

templates/ — 输出骨架

当输出格式复杂、有占位符需要填充时，拆到模板文件中。SKILL.md 只需要说"参考 templates/xxx"。

# templates/finding-template.md

### {severity_emoji} [{severity}] {title}
- **文件**: {file_path}
- **行号**: {line_number}
- **问题**: {description}
- **建议**: {recommendation}

---
**统计**: 🔴 {high} | 🟡 {medium} | 🟢 {low}

references/ — 知识库

团队规范、行业标准、审查清单等不会每次都变的参考资料。避免在 SKILL.md 里重复写长篇规范。

# references/review-checklist.md

## 代码审查清单
- [ ] 输入验证是否完整
- [ ] 错误处理是否覆盖所有异常路径
- [ ] 是否有硬编码的密钥或配置
- [ ] 日志是否包含敏感信息
- [ ] 方法长度是否超过 30 行

什么时候该拆：SKILL.md 超过 500 行时，说明你需要拆分了。把模板和参考资料移到对应目录，SKILL.md 只保留核心流程。

安装位置

Skill 放在哪，决定谁能用

项目级（团队共享，随 Git 同步）
your-project/
└── .claude/skills/
    └── code-review/
        └── SKILL.md

个人级（跨项目通用，不进 Git）
~/.claude/skills/
└── blog-draft/
    └── SKILL.md

内置（随 Claude Code 自带）
/simplify、/loop、/debug、/claude-api、/batch

位置	作用域	共享方式	适合放什么
`.claude/skills/`	当前项目	Git 同步	团队标准流程、项目专属 Skill
`~/.claude/skills/`	所有项目	不共享	个人习惯、跨项目通用 Skill
内置	全局	自动	简化、调试、循环等基础能力

查看已安装 Skill：在 Claude Code 中输入 /skills，可以看到当前可用的所有 Skill 列表及其触发条件。

日常管理

Skill 不是写完就完了——测试、更新、权限控制

测试 Skill

把 Skill 放到一个测试目录或临时项目里，通过命令触发验证。不要直接在生产项目中调试。

# 方法 1：在测试项目中触发
mkdir /tmp/test-skill && cd /tmp/test-skill
mkdir -p .claude/skills/my-skill
# 复制 SKILL.md 到目录中，然后在 Claude Code 中触发

# 方法 2：用 /skills 查看是否被发现
/skills

更新 Skill

修改 SKILL.md 或支持文件后，重新打开会话或重新加载即可生效。

改了 description → 重新加载后触发行为会变
改了模板或参考资料 → 下次调用自动用新版
加了新文件 → 确保在 SKILL.md 中有引用

限制访问

通过权限配置控制 Claude 能访问哪些 Skill：

disable-model-invocation: true → 禁止自动触发
allowed-tools → 限制可用工具范围
删除或移走 Skill 目录 → 彻底不可见

上下文注入

让 Skill 在执行时自动获取当前项目的动态信息

Skill 不是静态的提示词。它可以在加载时自动获取项目的实时信息，不需要用户手动粘贴。

$ARGUMENTS — 接收参数

用户输入 /pr-review auth-module 时，$ARGUMENTS 的值就是 auth-module。用 $0、$1 可以按位置取参数。

!`command` — 执行 Shell

在 SKILL.md 中用反引号包裹 Shell 命令，前面加 !。加载时会自动执行并插入结果：

- 当前分支：!`git branch --show-current`
- 变更统计：!`git diff --stat main...HEAD`
- 文件数量：!`find src -name "*.ts" | wc -l`

为什么重要：没有上下文注入，Skill 就是一段死模板。有了它，Skill 能感知当前项目状态——在哪个分支、改了什么文件、有多少测试——输出才会精准。

本仓示例

看看不同复杂度的 Skill 长什么样

code-review

全面代码审查，含模板和审查清单。中等复杂度的代表——有 SKILL.md + templates + references。

中等

refactor

重构规划与执行，含代码味道库。高复杂度——多步骤、多模板、参考资料很厚。

复杂

blog-draft

博客文章撰写，含大纲和草稿模板。低复杂度——只有 SKILL.md + 一个模板。

简单

brand-voice

品牌语气检查，含语调示例。同样简单，但展示了"纯参考资料"型 Skill。

简单

建议学习顺序：先看 blog-draft（最简单），再看 code-review（模板 + 参考），最后看 refactor（多步骤编排）。

实战示例

三种典型场景的 Skill 设计思路

代码库可视化

把代码库结构、依赖关系和模块边界总结给 Claude，便于快速理解项目。

# SKILL.md 片段
---
name: codebase-viz
description: 可视化代码库结构、依赖和模块边界
allowed-tools: Bash(tree *), Read, Glob
---
## 执行步骤
1. 用 tree 命令获取目录结构
2. 分析 package.json / Cargo.toml 等依赖
3. 识别模块边界和层级关系
4. 输出结构图和依赖摘要

CLAUDE.md 生成

从项目文档中自动生成或补充 CLAUDE.md，确保 Claude 对项目的理解始终最新。

# SKILL.md 片段
---
name: claude-md-gen
description: 从项目文档生成或补充 CLAUDE.md
allowed-tools: Read, Glob, Write
---
## 执行步骤
1. 扫描 README、docs/、CHANGELOG 等
2. 提取架构约定、API 格式、测试要求
3. 生成或合并到 CLAUDE.md

部署（仅用户触发）

带副作用的操作必须禁止自动触发，只允许用户手动调用。

# SKILL.md 片段
---
name: deploy
description: 部署到生产环境
disable-model-invocation: true
allowed-tools: Bash(deploy *), Bash(docker *)
---
## ⚠️ 安全约束
此 Skill 有副作用，禁止自动触发。
只有用户明确输入 /deploy 时才执行。

Skill 的位置

Skill 在 Memory 和 Subagent 之间——约束、方法、执行三层协作

作为方法层

Skill 在 Memory 和 Subagent 之间扮演什么角色

Memory

底座约束
定义"应该怎样"

Skill

方法 + 模板
定义"怎么做"

Subagent

执行角色
定义"谁来做"

稳定输出

可复用结果
可汇总消费

举个例子：你在 CLAUDE.md（Memory）里写了"使用 TypeScript 严格模式"。你在 code-review Skill 里定义了"按安全性、质量、可维护性三个维度审查，输出参考 finding-template.md"。然后你让一个 subagent（只读权限的审查专家）去执行这个 Skill。

角色	做什么	例子
Memory	定义"应该怎样"（约束）	"使用 TypeScript 严格模式"
Skill	定义"怎么做"（方法 + 模板）	审查步骤 + 审查模板
Subagent	定义"谁来做"（角色）	安全审查专家

一句话记住：Memory 是约束底座，Skill 是方法手册，Subagent 是执行角色。三者配合 = 稳定的、高质量的、可复用的输出。

功能对比

Skills、Slash Commands、Subagents、Hooks 各有分工

功能	触发方式	核心定位	适合场景
Skills	自动 / 半自动 / `/` 手动	可复用的能力包	流程标准化、输出模板化
Slash Commands	手动 `/command`	快捷入口	一键执行固定操作
Subagents	Claude 自动委派	隔离执行角色	并行任务、独立上下文
Hooks	事件触发（提交前、工具调用前等）	自动化钩子	校验、拦截、自动化流程

选择逻辑

需要复用 + 模板 → Skill
只需要一个入口 → Slash Command（现在推荐用 Skill 做）
需要隔离上下文 → Subagent
需要在特定事件自动执行 → Hook

组合使用

最强大的做法是组合：Skill 定义方法，Subagent 执行，Hook 在提交前自动触发 Skill 做检查。

隔离运行

某些 Skill 适合在 Subagent 的隔离上下文中运行

为什么需要隔离

降低主会话干扰：审查、分析等只读 Skill 不需要污染主对话历史
独立权限控制：Subagent 可以有更窄的工具白名单
并行执行：多个 Skill 同时跑，互不影响

典型场景

代码审查 → 让审查 Subagent 运行 code-review Skill
安全扫描 → 隔离环境运行，结果汇总回主会话
文档生成 → 独立上下文避免和代码实现混淆

做法：在 SKILL.md 的 agent 字段或 context 字段中指定运行环境。详细配置见下一章 Subagents。

安全守则

Skill 涉及自动执行，安全意识必须到位

不要硬编码密钥

Skill 文件会进入 Git 仓库，绝对不能把 API Key、数据库密码等写死在 SKILL.md 或脚本里。用环境变量或 !`echo $API_KEY` 动态注入。

副作用操作保持用户触发

部署、删除、发邮件等有副作用的操作，必须设置 disable-model-invocation: true，确保只有用户明确要求时才执行。

给自动触发设清晰边界

自动触发的 Skill 要有明确的触发范围——通过精确的 description 和 allowed-tools 白名单，防止 Claude 在不相关的场景滥用。

安全检查清单：每次新建或修改 Skill 时，问自己三个问题——有没有密钥泄露风险？有没有未限制的副作用操作？自动触发的范围是否足够精确？

排错指南

SKILL.md 太长

症状：SKILL.md 超过 500 行，Claude 执行时容易丢重点。

修复：把模板拆到 templates/，参考资料拆到 references/。SKILL.md 只保留触发条件、执行步骤和输出格式说明。

占位符不明确

症状：模板里写了 {data}，Claude 填出来的东西完全不对。

修复：把 {data} 改成 {user_id: string}，给占位符加类型说明和示例值。

description 太模糊

症状：Claude 在不相关的场景也自动激活了这个 Skill。

修复：把 "做审查" 改成 "对代码变更进行安全性、可维护性、代码质量三维度审查"。越具体，触发越精准。

把项目细节写死了

症状：Skill 里硬编码了特定项目的配置路径，换个项目就报错。

修复：把项目相关配置放到 CLAUDE.md（Memory），Skill 只保留通用方法论。用 $ARGUMENTS 和 !`cmd` 动态获取项目信息。

Skill 没有触发

症状：输入了相关指令，但 Claude 没有调用 Skill。

修复：① 检查 description 是否足够具体；② 检查目录是否在 Claude 可见范围内（.claude/skills/）；③ 检查是否被更高优先级的 Skill 覆盖。

Skill 触发太频繁

症状：Claude 在不相关的场景也自动激活了这个 Skill。

修复：收紧 description，增加约束条件，用更具体的触发词。例如把"做审查"改成"对 PR 变更进行代码质量审查"。

看不到全部 Skills

症状：输入 /skills 看到的列表比预期少。

修复：① 检查路径是否正确（项目级 vs 个人级）；② 检查文件权限；③ 重新加载会话让 Claude 重新扫描。

动手练习

做一个最小 PR Review Skill

停下来，自己动手做一个。只有你自己写出来的 Skill，才是你的。

最小版本

创建 Skill 目录结构
写一个 SKILL.md，包含触发条件、审查维度、输出格式
创建 1 个审查发现模板文件
确认 /pr-review 能触发

进阶挑战

加一个 references/review-checklist.md
用 !`git diff --stat main...HEAD` 注入变更统计
思考：这个 Skill 该不该设 disable-model-invocation？

提示：先只做最小版本——SKILL.md + 一个模板文件。跑通之后再加参考资料和上下文注入。不要一口气写太多。关于进阶挑战中的 disable-model-invocation：想一想 PR 审查有没有副作用——如果没有，设不设都行；如果 Skill 会自动提交评论或修改文件，设为 true 更安全。

参考答案

一种可行的 pr-review Skill 写法

# 文件：.claude/skills/pr-review/SKILL.md

---
name: pr-review
description: 对 PR 进行安全和质量审查
argument-hint: "[pr-number]"
allowed-tools: Bash(git *), Read, Grep
---

# PR Review

## 触发条件
当用户请求 PR 审查、代码变更审查时自动激活。

## 上下文
- 当前分支：!`git branch --show-current`
- 变更统计：!`git diff --stat main...HEAD`

## 执行步骤
1. 获取变更文件列表和 diff
2. 按审查维度逐项检查
3. 按严重程度分类发现
4. 使用 templates/finding-template.md 格式化输出

## 审查维度
1. 安全性（输入验证、权限、敏感数据）
2. 代码质量（命名、结构、可读性）
3. 测试覆盖（是否有对应测试）

## 输出格式
参考 templates/finding-template.md

# 文件：.claude/skills/pr-review/templates/finding-template.md

## 审查结果

### {severity_emoji} [{severity}] {title}
- **文件**: {file}
- **行**: {line}
- **问题**: {issue}
- **建议**: {fix}

---
**审查统计**: 🔴 {high} | 🟡 {medium} | 🟢 {low}

别直接照抄：重点不是这段文本，而是你能不能解释——为什么触发条件要写具体？为什么模板要拆成独立文件？为什么 allowed-tools 只给了 git *、Read、Grep 而不是全部权限？

本章回顾

从"每次重新描述"到"一键复用稳定输出"

到这里，你已经能

说清 Skill 由哪些文件构成、各自职责
理解渐进式加载为什么重要
创建一个带模板的最小 Skill
判断"这个需求该做 Skill 还是做 Command"
理解 Skill 在 Memory → Skill → Subagent 链路中的定位

它和前后章节的关系

Memory — 为 Skill 提供约束底座
Skills — 定义"怎么做"和"输出长什么样"
Subagents — 把 Skill 交给专门的执行角色
Plugins — 把多个 Skill 打包成可安装方案

核心结论：Skill 是"方法论 + 模板"的固化。好的 Skill = 具体的触发条件 + 清晰的执行步骤 + 可复用的输出模板。你今天写好的第一个 code-review Skill，可能就是下周团队每个人都在用的标准流程。