不知道你有没有过这样的体验：装上 Claude Code 之后，聊聊天、改改小文件都挺顺手，但一碰到稍微复杂一点的项目，就感觉它“差点意思”。其实问题大概率不在模型，而在工作流。Claude Code 真正的优势不是“把对话生成代码”，而是它作为一个终端里的 AI 编程代理（Agent），可以被高度定制。而定制的关键入口，就是 Skill，也就是社区里常说的“插件”“技能包”。
这一期我们不聊 API 文档，也不灌概念，直接讲一个可落地的组合方案：Claude Code 的三个实用 Skill 如何装、如何写、如何搭配，让它在日常开发里真正扛起“代码审查、测试生成、提交整理”这三类高频脏活。读完之后，你会有一个可以直接复制到仓库里的.claude/skills目录，以及一套能长期维护的 Skill 写法。
1. 这篇文章真正要解决的问题
很多人接触 Claude Code，都是从“在终端里问它问题”开始的。这种用法不能说错，但效率天花板很低。原因在于：普通聊天式 AI 是“你说一句，它回一句”，它记不住你的项目规范，也不知道你团队的代码风格，更不会主动按你的标准去审查代码。每次都要把背景重新交代一遍，时间一长，人就会烦。
Skill 解决的是另外一个层次的问题：把“你希望 AI 怎么做”变成一份可复用的说明书。你写好一个 Skill 文件，Claude Code 会在合适的场景下自动读取它，按照里面定义的步骤来执行任务。这个机制很像给 AI 写 SOP，也像把团队的新人培训手册装进了编辑器。
这篇文章要解决的核心痛点有三个：
- 不知道怎么开始：Skill 目录建在哪、文件叫什么、内容写什么，很多人卡在第一步。
- 不知道怎么写才有效：写了一个 SKILL.md 但 Claude 不调用，或者调用后效果很弱，大多是因为 description 和正文结构写得有问题。
- 不知道如何组合：单个 Skill 能提升一点效率，但组合起来才能形成完整工作流。比如提交代码前先审查、审查完后补测试、最后生成规范的 commit message，这本来就是一个开发闭环。
所以，这篇内容更适合谁？如果你已经装过 Claude Code，但感觉没发挥出真正价值；或者你是团队里负责引入 AI 工具的人，想让 AI 编程真正“按团队规范”走，而不是靠人肉提示词，那这篇文章值得你完整看完。
2. Claude Code、Skill 与 Agent：三个容易混淆的概念
在动手写 Skill 之前，先把三个高频词讲清楚。它们经常被混着说，但实际是不同层次的概念。
2.1 Claude Code 是一个终端 Agent
Claude Code 是 Anthropic 推出的命令行 AI 编程工具。它不是一个普通的对话窗口，而是一个能感知项目上下文、执行工具调用、读写文件、运行命令的代理程序。你可以在 VSCode 的终端里启动它，也可以直接在各系统终端里使用。它最核心的特点是“能动手”：不仅会建议你改哪一行，还能直接修改文件、运行测试、查看结果。
2.2 Skill 是给 Agent 的“技能说明书”
Skill 官方称之为“Skills”，社区里常叫“插件”“技能包”。它的物理形态就是一个文件夹加一个 Markdown 文件。你可以把它理解为给 Claude Code 准备的一份“岗位说明书”：里面写清楚这个技能什么时候触发、按什么步骤执行、输出什么格式。
Skill 与提示词的区别在于：提示词是一次性的，需要你每次手动输入；Skill 是持久化的，它挂在项目目录或用户目录下，Claude 会根据任务内容，在合适的时机自动参考这些说明。用一句不严谨但好记的话来说：提示词是在“问问题”，Skill 是在“定规矩”。
2.3 Agent 是执行者，Skill 是能力模块
Agent 本身是一个主体，它负责理解任务、调用工具、决定下一步动作。Skill 则是给 Agent 注入的“能力模块”。一个 Agent 可以加载多个 Skill，就像一名工程师同时掌握代码审查、测试编写和 Git 规范整理三种能力。Skill 之间还能互相配合，这就是“组合插件”的含义。
2.4 对比：普通对话、Agent、Skill 的边界
| 维度 | 普通对话式 AI | Claude Code Agent | Claude Code + Skill |
|---|---|---|---|
| 是否感知项目上下文 | 否 | 是 | 是 |
| 是否自动执行操作 | 否 | 是 | 是 |
| 是否记住团队规范 | 否 | 弱 | 强 |
| 是否需要重复交代背景 | 每次都要 | 部分需要 | 不需要 |
| 可复用性 | 低 | 中 | 高 |
看完这张表，你应该能理解一个判断：如果只把 Claude Code 当聊天框用，那你用的是它最浅的一层能力；只有开始写 Skill，才真正进入“用 AI 搭建工程流水线”的阶段。
3. 环境准备与前置条件
这一节我们先保证 Claude Code 能跑起来，再进入 Skill 部分。版本信息以你安装时的官方文档为准，这里演示的是通用思路。
3.1 基础环境：Node.js 与 npm
Claude Code 目前主要通过 npm 分发，因此需要 Node.js 环境。建议使用 Node.js 18 及以上版本，低于这个版本时，很多新版功能可能无法正常工作。检查命令：
node -v npm -v如果还没有安装 Node.js，可以去 Node.js 官方站点下载 LTS 版本，或者使用 nvm 这类版本管理工具安装。nvm 的好处是可以在多个 Node 版本之间切换，不会污染全局环境。
3.2 安装 Claude Code
全局安装的命令：
npm install -g @anthropic-ai/claude-code安装完成后，检查版本：
claude --version如果能正常输出版本号，说明安装成功。如果提示claude: command not found，大概率是 npm 的全局 bin 目录没有加入系统 PATH，后面常见问题里会展开讲。
3.3 登录与鉴权
首次运行需要在终端执行：
claude弹窗界面会引导你完成登录。在生产环境中，更推荐使用 API Key 方式，便于在服务器或 CI 环境里使用：
export ANTHROPIC_API_KEY=你的密钥这里要提醒一句：密钥属于敏感信息，不要把它写进项目代码或提交到 Git 仓库。团队协作时，建议使用环境变量管理工具或密钥管理服务。
3.4 网络受限环境的安装策略
如果你所在网络环境访问 npm 或 GitHub 不稳定，安装可能会卡住。这种情况下的处理方式和“下载慢”还不完全一样，可以从三个方向优先尝试：
- 切换 npm 镜像源，使用国内可访问的 registry。
- 优先使用 npm 包方式安装，避免直接下载 GitHub 仓库压缩包。
- 如果项目依赖来自 GitHub，可以找项目是否提供了 npm 包或镜像仓库地址。
这些都属于常规的依赖获取问题，不要因此下载来源不明的“加速工具”或“绿色版安装包”。另外，如果你当前使用的模型端点和 Community 实验配置，和官方模型名不对应，后续也会出现模型识别问题，这一点在第 7 节的排查表里会专门说明。
4. Skill 的核心机制与目录规范
安装好 Claude Code 之后，下一步就是理解 Skill 的存放位置和文件规范。
4.1 项目级 Skill 目录
最常用的是项目级 Skill。在项目根目录下，创建一个.claude/skills目录，里面每个子目录就是一个 Skill。结构如下：
你的项目/ └── .claude/ ├── CLAUDE.md ├── settings.json └── skills/ ├── code-review/ │ └── SKILL.md ├── test-writer/ │ └── SKILL.md └── commit-helper/ └── SKILL.md.claude/CLAUDE.md：项目级记忆文件。用来写团队的长期约定，比如“本项目使用 TypeScript”“提交信息必须符合 Conventional Commits”。Claude 每次任务都会参考它。.claude/settings.json：工具权限控制文件。可以限制 Claude 能执行的命令范围，属于安全边界的一部分。.claude/skills/<skill-name>/SKILL.md：每个 Skill 的核心内容。
4.2 SKILL.md 的文件格式
SKILL.md 分为两部分：开头的 YAML frontmatter，以及正文的 Markdown 指令。
--- name: skill-name description: 在什么时候、什么场景下使用这个 Skill --- 这里是具体的执行步骤和规则。frontmatter 里两个字段最关键：
name：Skill 的名字，一般用小写字母加连字符。这个名字会用于调用和日志展示。description：Claude 判断“什么时候该用这个 Skill”的依据。这句话写得越具体，Skill 被正确触发的概率越高。
4.3 description 怎么写才不会被“无视”
很多人写完 Skill 后发现 Claude 压根不调用，问题几乎都出在 description 上。description 需要满足三个条件：
- 以动词开头，明确指出触发动作，比如“当需要审查代码时使用”“当需要生成单元测试时使用”。
- 写清楚适用对象，比如“针对 Python 函数”“针对当前 Pull Request 的改动”。
- 不要写成模糊的“帮我做事”，而要写成“遇到这类需求时，读取并遵循此 Skill 的规则”。
下面是一个反例和一个正例：
反例：
description: 代码审查技能，用于提升代码质量。正例：
description: 当用户要求审查代码、检查 PR、或评估代码质量和安全隐患时使用。按安全、性能、可读性、测试覆盖四个维度输出结论。区别很明显：反例像一句口号，Claude 无法判断什么时候触发；正例给出了明确的触发条件和输出方式。
4.4 项目级与用户级 Skill
项目级 Skill 放在仓库目录下，最适合团队共享。因为一旦提交到 Git，所有克隆仓库的成员都会拿到这套规范，新人入职看到.claude目录，就能立刻了解团队对 AI 的使用约定。
如果你有自己固定的一套通用 Skill，不想每个项目重复粘贴，也可以放在用户级目录下。具体路径在不同版本中可能不同，建议安装后查看官方文档。
更稳妥的判断是：通用能力放用户级，项目相关规范放项目级。例如“提交信息规范”通常适合放项目级，因为每个团队的提交规范不一定相同；而“通用代码审查模板”这种不依赖具体语言的，可以放用户级。
5. 三个实用 Skill 组合实战
这一节是全文的重头。我们直接用命令创建一个可用的 Skill 组合，然后逐个解释 SKILL.md 的内容。
5.1 创建目录骨架
在项目根目录下执行：
mkdir -p .claude/skills/code-review mkdir -p .claude/skills/test-writer mkdir -p .claude/skills/commit-helper如果是在 Windows 上使用 CMD，可以用：
mkdir .claude\skills\code-review mkdir .claude\skills\test-writer mkdir .claude\skills\commit-helper创建完成后，目录结构应该和 4.1 节展示的一致。
5.2 Skill 1：code-review，把代码审查变成标准动作
先创建.claude/skills/code-review/SKILL.md，内容如下：
--- name: code-review description: 当用户要求审查代码、检查代码质量、评估 PR 或查看某个文件的安全风险时使用。按安全、性能、可读性、测试覆盖四个维度输出结论。 --- # Code Review Skill 请按以下流程审查代码： 1. 先读取目标文件，分析代码改动范围。 2. 按四个维度输出结论： - 安全性：注入风险、权限校验、敏感信息泄露、依赖安全问题。 - 性能：不必要的循环、重复请求、内存使用、IO 开销。 - 可读性与维护性：命名、函数长度、重复代码、模块划分。 - 测试覆盖：是否有对应测试、边界条件是否覆盖、异常路径是否处理。 3. 每个问题标注严重级别：严重（必须改）/ 建议（应该改）/ 提醒（可选优化）。 4. 不要输出空泛评价，所有意见必须能落到具体代码位置。 输出模板： ## 审查结论 整体质量：优 / 良 / 需改进 ### 严重问题 ### 建议问题 ### 可选优化这个 Skill 的价值在于：它把“代码审查”从一个模糊的对话请求，变成了一套固定输出格式。你不需要每次告诉 Claude“你要从哪几个维度看”，它自己会按模板来。
5.3 Skill 2：test-writer，把测试生成变成流程
第二个 Skill 用于生成单元测试。创建.claude/skills/test-writer/SKILL.md：
--- name: test-writer description: 当用户要求为某个函数、类或接口补充单元测试时使用。支持 Python、TypeScript、Java 等主流语言，自动匹配项目使用的测试框架。 --- # Test Writer Skill 1. 先分析目标模块的输入、输出和边界条件。 2. 根据项目语言选择测试框架： - Python：pytest - TypeScript / JavaScript：Vitest 或 Jest - Java：JUnit 5 3. 输出测试文件路径和完整测试代码。 4. 测试用例必须覆盖： - 正常输入路径。 - 空值、越界、非法参数等边界情况。 - 预期抛出异常的异常路径。 5. 如果项目已有测试风格，优先保持风格一致。 6. 生成结束后，给出当前项目运行测试的命令。这里有一个容易踩的坑：Claude 默认生成测试代码时，可能不会先检查项目已有的测试风格。如果你在description里不强调“保持项目风格一致”，它有时会生成一个写法完全不同的测试文件，虽然能跑，但会让维护者很头疼。加入第 5 条之后，Claude 会先看项目里已有的测试文件再动手。
5.4 Skill 3：commit-helper，把 Git 提交信息变成规范
第三个 Skill 负责 Git 提交信息。创建.claude/skills/commit-helper/SKILL.md：
--- name: commit-helper description: 当用户准备提交代码、需要编写 git commit message、或整理 CHANGELOG 时使用。将根据项目改动生成规范提交信息。 --- # Commit Helper Skill 1. 使用 git status 和 git diff --stat 查看本次改动文件。 2. 阅读有代表性的 diff，理解改动意图。 3. 按照 Conventional Commits 规范生成提交信息： <type>(<scope>): <subject> type 取值范围： - feat：新功能 - fix：修复问题 - docs：文档变更 - style：格式调整 - refactor：重构 - perf：性能优化 - test：测试相关 - chore：构建、依赖等杂项 4. 将提交信息展示给用户，获得确认后再建议执行 git commit。 5. 不要擅自提交代码，除非用户明确授权。很多人会觉得提交信息一个git commit -m "fix bug"就够了，没必要交给 AI。但实际上，在多分支协作或需要生成 CHANGELOG 的项目里，提交信息的规范性直接影响后续的自动化发布和版本追溯。如果团队准备接语义化版本发布流程，这一条 Skill 的价值会立刻体现。
5.5 用 CLAUDE.md 把三个 Skill 串起来
三个 Skill 单独用都有效，但组合起来才更像“一条流水线”。这个组合的关键，是在.claude/CLAUDE.md里定义固定顺序：
// .claude/CLAUDE.md 团队开发约定： 1. 修改代码后，先运行 test-writer 生成或补充单元测试。 2. 提交代码前，使用 code-review 完成一次审查。 3. 最终提交时，使用 commit-helper 生成规范提交信息。 4. 涉及破坏性变更时，必须同时给出回滚方案。CLAUDE.md 的作用是“长期记忆”。Claude 在每次执行任务时都会参考它，所以它会知道“这个团队要求先补测试、再审查、最后规范提交”。三个 Skill 就不再是孤立的提示词，而是被统一到一个工作流里。
5.6 交互式调用示例
启动 Claude Code：
claude在交互界面中输入：
@code-review 审查 src/main.py或者一次性做多步：
请为 utils/date.py 生成单元测试，然后审查一下测试代码。如果你希望跳过交互，直接以非交互方式执行，可以用：
claude -p "@test-writer 为 utils/date.py 生成 pytest 用例"这种非交互方式适合在脚本中调用，后面验证时会用到。
6. 运行效果与验证方法
Skill 配好后，怎么判断它是真的生效，而不是假装生效？这一节给出可执行的验证步骤。
6.1 验证 Skill 目录被识别
在 Claude Code 交互界面中，输入斜杠命令查看当前会话可用的技能列表。
/help或者直接输入 Skill 名看是否有补全提示：
@code-review如果输入@后能看到code-review、test-writer、commit-helper三个选项，说明 Skill 已经被加载。
6.2 用一个最小函数验证 code-review
先创建一个测试文件：
# 文件路径：src/example.py def get_user_name(user_id, db): sql = "SELECT name FROM users WHERE id = " + user_id return db.execute(sql)然后在 Claude Code 中调用：
@code-review 审查 src/example.py预期输出中应该包含四个维度：安全性（SQL 注入风险）、性能（无大问题，但建议使用参数化查询）、可读性（函数命名没问题，但缺少类型注解）、测试覆盖（缺少测试）。如果输出只是“代码写得不错”这类评价，说明 Skill 的正文没有被正确读取，需要检查 frontmatter。
6.3 验证 test-writer
继续用上面这个例子：
claude -p "@test-writer 为 src/example.py 生成 pytest 测试"预期输出会包含一个test_example.py的代码块，并且至少覆盖正常路径和异常路径。你可以把生成的代码保存下来，用 pytest 手动运行确认。
6.4 验证 commit-helper
在项目工作区做一次改动后，调用：
@commit-helper 帮我生成提交信息预期输出是一行类似下面的信息：
fix(users): 使用参数化查询修复用户查询的 SQL 注入风险如果没有生成这种格式，而是给了一堆废话，说明 SKILL.md 中的模板没有被遵循，或者当前版本对 Markdown 指令的理解方式和你预期不同，可以适当把步骤写得更短、更指令化。
6.5 失败时的第一排查顺序
如果运行结果不符合预期，不要急着改内容，先按顺序查：
- 目录名和文件名是否完全正确：必须是
.claude/skills/<skill-name>/SKILL.md。 - frontmatter 是否使用了
---包裹。 description是否准确描述了当前任务场景。- 是否调用了正确的 Skill 名。
- 当前 Claude Code 版本是否过旧，旧版本可能不支持新加的 Skill 功能。
7. 常见问题与排查思路
下面把实际使用中最高频的问题整理成一张排查表。
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
claude: command not found | npm 全局 bin 目录不在 PATH 中 | 执行npm prefix -g查看全局目录 | 将该目录加入系统 PATH，重开终端 |
| Skill 明明写了却不生效 | 目录位置写错，或 SKILL.md 文件名错误 | 检查是否在.claude/skills/<name>/SKILL.md | 按规范重建文件，注意大小写 |
输入@skill-name没反应 | frontmatter 缺失或解析失败 | 用编辑器检查文件头部是否被 BOM 干扰 | 删除 BOM，确认name字段正确 |
| Claude 不主动调用 Skill | description 写得像口号，无法触发 | 重读 description 是否包含触发场景 | 改成“当用户要求……时使用”句式 |
| 生成内容总是不符合团队风格 | 缺少项目级约定 | 查看.claude/CLAUDE.md是否为空 | 在 CLAUDE.md 中补充团队规范 |
提示"xxx" is not a model this version of claude code recognizes | 使用了当前版本无法识别的模型名或实验性配置 | 检查当前claude --version版本，确认模型名 | 恢复官方默认模型，或升级 Claude Code 后再试 |
| 下载安装时进度卡住 | 网络环境受限 | 观察 npm 日志和下载地址 | 切换 npm 镜像源，重试安装 |
| 工具执行被拒绝 | 当前权限配置限制了命令 | 查看settings.json中的权限设置 | 按最小权限原则放开明确需要的命令，生产环境需人工审批 |
这里的模型名报错需要特别说明：这个问题通常出现在用户手动配置了第三方模型端点或实验性模型名之后。AI 编程工具对模型名的识别和当前版本强相关，在没有官方文档明确支持的情况下，不建议在生产环境使用未经验证的模型名。稳妥的做法是保持 Claude Code 默认模型配置。
8. 最佳实践与工程建议
Skill 写得好不好，不是看代码多少，而是看“触达率”和“稳定性”。触达率是指任务出现时 Skill 能被正确调用的概率；稳定性是指无论 Claude 怎么理解，输出结果都能保持近似格式。下面这组建议能同时提升两者。
8.1 Skill 设计原则：一个 Skill 只做一件事
不要把“代码审查、写文档、生成测试、处理 Git”全部塞进一个 SKILL.md。一个 Skill 只负责一个职责，原因有两点：
- description 更容易写清楚，Claude 调用时会更快匹配。
- 正文更短，模型不会“读了后半段忘了前半段”。
如果发现一个 SKILL.md 里出现了两套不相关的步骤，就应该拆成两个 Skill。
8.2 description 的统一句式
推荐在这种格式中填充：
description: 当用户要求{动作}时使用。适用于{场景}。输出应按{格式}完成。例如：
description: 当用户要求编写提交信息时使用。适用于正在准备 git commit 的开发者。输出应符合 Conventional Commits 规范。这个句式把“触发条件、适用对象、输出要求”三个关键信息都覆盖了。
8.3 把 Skill 纳入版本管理
.claude/skills目录建议提交到 Git 仓库。这样团队每个成员 Clone 后都会自动获得同一套技能配置，不会出现“我本地可以、你本地不行”的情况。
建议在仓库的 README 中加一节说明：
## AI 辅助开发 本仓库使用 Claude Code 作为 AI 编程辅助工具。 - 代码审查：@code-review - 单元测试：@test-writer - 提交信息：@commit-helper8.4 安全边界：让 AI 动代码前先确认
Skill 赋予了 Claude 执行任务的能力，但能力越强，越需要边界。建议从三个层面控制：
- 权限层：通过
.claude/settings.json控制哪些命令允许自动执行，哪些必须询问用户。 - 内容层：不要在 SKILL.md 中写入任何密钥、内部域名、敏感路径和涉密信息，因为它是项目文件，会被提交到仓库并共享。
- 操作层：涉及删除文件、修改数据库结构、发布产物等危险操作时，让 AI 先输出执行计划，等待人工确认后再执行。
8.5 模型接入：稳定优先
平时关注 AI 编程工具的同学，可能会看到社区里有人把 Claude Code 接到其他模型上实验。这类玩法适合学习和研究，但不建议直接引入生产环境。最直接的原因就是兼容性：不同模型对工具调用的格式、上下文长度、指令遵循程度的差异很大，某个版本能用，升级后可能就报“model not recognized”之类的错误。
如果你真的想尝试，唯一正确的做法是：在独立环境里做实验，使用官方文档明确支持的模型名，并且保证切换失败时可以快速回滚默认配置。生产环境保持原厂配置，这是最稳的选择。
8.6 Skill 的维护节奏
Skill 不是写一次就一劳永逸的。建议在以下时刻主动更新：
- 团队规范发生变化时。
- Claude Code 大版本升级后，用现有 Skill 跑一遍旧任务，确认输出没有明显退化。
- 发现 Skill 生成的输出总是需要人工二次修改时，应该修改 Skill 正文补充约束，而不是每次手动纠正。
9. 总结与下一步实践
这篇文章的核心脉络可以浓缩成三句话：
第一，Claude Code 的价值不在对话，而在 Agent 能力；Skill 是给它注入能力的标准方式。
第二，一个 Skill 就是一个SKILL.md文件，关键是写清楚description触发时机和正文的执行步骤，目录规范是.claude/skills/<skill-name>/SKILL.md。
第三，三个实用 Skill 可以组合成一条连贯的开发流程：test-writer补测试、code-review做审查、commit-helper保证提交规范。组合起来之后，它就不再是三个孤立的提示词，而是一套可复用的团队工程规范。
如果你刚接触这块，建议现在动手做一件最小的事：在任意一个最常用的 Git 项目里，创建.claude/skills/commit-helper/SKILL.md，把第 5.4 节的代码复制进去，然后下次提交代码时试着调用一次。跑通这一个，再逐步加上测试生成和代码审查。不要一次性把十几个 Skill 全部堆进仓库，Skill 越多，维护成本越高，先用最小集跑通日常流程，再按实际需要扩充。
另外，给一个新入门的团队一个建议：Skill 的引入最好和团队现有流程绑定，而不是另起炉灶。比如你们已经在用 Conventional Commits，那就把 commit-helper 直接对应到现有规范；你们已经有一套代码评审检查单，那就把 code-review 的内容改成团队自己的版本。这样 AI 不是替代原有流程，而是在原流程里多了一个稳定的执行者。过一个月回头看，你会发现真正有价值的不是某个 Skill 的写法，而是这套“把团队规范固化成 AI 可执行指令”的思维方式。
