1. 什么是 Claude Code Skills
Claude Code Skills 是 Anthropic 为 Claude Code 引入的一项可扩展能力，它允许你把重复性的指令、脚本、参考文档和资源打包成一个可复用的技能单元。当你在对话中触发某个 Skill 时，Claude 会自动加载该技能的定义文件（SKILL.md），并严格遵循其中的规则、工作流和工具调用方式来完成任务。
简单理解，Skills 就是「给 Claude 安装的职业技能包」。比如你可以创建一个「代码审查」Skill，里面写好审查清单、报告模板和静态分析脚本，之后每次说一句「用我的代码审查技能检查这个模块」，Claude 就会按照你定义的流程执行，而不是每次都重新描述一遍要求。
Skills 的核心价值在于：
- 可复用：一次定义，处处使用，告别反复粘贴同一个提示词。
- 可组合：一个 Skill 可以同时包含指令、脚本、模板和参考资料。
- 可共享：Skill 以文件夹形式存在，可以提交到仓库、打包成插件分发给团队。
- 渐进式加载：Claude 只在需要时读取对应 Skill，不会把所有内容都塞进上下文。
2. 环境准备与安装
在开始之前，需要先安装 Claude Code。截至本文写作时，推荐使用 Node.js 环境，要求 Node.js 18 及以上版本。
2.1 检查 Node.js 版本
node--version# 建议输出 v18.x、v20.x 或 v22.x如果未安装 Node.js，可以从 nodejs.org 下载 LTS 版本，或使用 nvm 安装：
# 安装 nvm（macOS / Linux）curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh|bashsource~/.bashrc# 安装并使用 Node.js 20nvminstall20nvm use202.2 安装 Claude Code
通过 npm 全局安装：
npminstall-g@anthropic-ai/claude-code安装完成后验证：
claude--version也可以使用 macOS 的原生安装器：
curl-fsSLhttps://claude.ai/install.sh|bash2.3 首次启动与登录
# 进入你的项目目录cdyour-project# 启动 Claude Codeclaude首次启动会要求完成账号认证。认证完成后，Claude Code 会在你的用户目录和项目目录中初始化配置。
3. Skill 的核心结构：SKILL.md
每个 Skill 本质上是一个目录，目录名即 Skill 的唯一标识。目录内至少包含一个SKILL.md文件，它是这个技能的「说明书 + 指令集」。一个典型的 Skill 目录结构如下：
.claude/skills/ └── code-reviewer/ # Skill 目录，名称用于标识 ├── SKILL.md # 必填：技能定义文件 ├── scripts/ # 可选：辅助脚本 │ ├── lint.sh │ └── format_report.py ├── references/ # 可选：参考资料，按需加载 │ ├── checklist.md │ └── team-conventions.md └── assets/ # 可选：模板等静态资源 └── report-template.md3.1 SKILL.md 的 YAML Frontmatter
SKILL.md文件必须以上下文（frontmatter）开头，用三横线包裹，字段定义如下：
--- name: code-reviewer description: 用于审查代码质量、安全性和团队规范符合度的技能。在用户要求审查代码、检查 PR、评估代码质量时使用。 ---name：Skill 名称，需与目录名保持一致，只能包含小写字母、数字和连字符。description：触发描述。这一行直接决定 Claude 何时自动调用你的 Skill，要写清楚「什么场景下使用」，而不是单纯描述功能本身。
3.2 SKILL.md 正文指令
frontmatter 之后就是正文，可以自由编写 Markdown，告诉 Claude 在执行该 Skill 时需要遵守的规则、步骤和约束：
--- name: code-reviewer description: 用于审查代码质量、安全性和团队规范符合度的技能。在用户要求审查代码、检查 PR、评估代码质量时使用。 --- # 代码审查技能 ## 审查步骤 1. 阅读待审查文件的完整内容。 2. 运行 `scripts/lint.sh` 获取静态分析结果。 3. 对照 `references/checklist.md` 逐项检查。 4. 按下方模板输出审查报告。 ## 审查维度 - 正确性：逻辑错误、边界条件、空值处理。 - 安全性：注入漏洞、敏感信息泄露、权限校验。 - 规范性：命名、注释、代码风格是否符合团队约定。 ## 输出格式 必须使用 `assets/report-template.md` 中的模板生成报告。4. 创建你的第一个 Skill
下面通过一个完整例子，手把手创建第一个 Skill：git-commit，它的作用是「根据当前暂存区的变更自动生成符合 Conventional Commits 规范的提交信息」。
4.1 确定 Skill 存放位置
Claude Code 支持两个级别的 Skill 目录：
| 级别 | 存放路径 | 作用范围 |
|---|---|---|
| 用户级 | ~/.claude/skills/ | 所有项目均可使用 |
| 项目级 | .claude/skills/ | 仅当前项目可用，适合随仓库共享 |
本例使用项目级，方便团队共享：
cdyour-projectmkdir-p.claude/skills/git-commitcd.claude/skills/git-commit4.2 编写 SKILL.md
创建SKILL.md：
touchSKILL.md编辑内容：
--- name: git-commit description: 根据 git 暂存区的代码变更，生成符合 Conventional Commits 规范的提交信息。在用户要求写 commit message、提交代码时使用。 --- # Git Commit 消息生成技能 ## 任务 分析 `git diff --cached` 的输出，生成一条简洁、符合 Conventional Commits 规范的提交信息。 ## 执行步骤 1. 运行 `git diff --cached --stat` 查看变更文件概览。 2. 运行 `git diff --cached` 查看具体变更内容。 3. 总结变更的核心意图，确定提交类型： - `feat`：新增功能 - `fix`：修复缺陷 - `docs`：文档变更 - `style`：代码格式（不影响逻辑） - `refactor`：重构 - `test`：测试相关 - `chore`：构建或辅助工具变更 4. 生成提交信息，格式如下： ```text <type>(<scope>): <subject> <body>约束
- subject 不超过 50 个字符，使用祈使句，首字母小写。
- body 解释「为什么」和「做了什么」，不写显而易见的内容。
- 只输出提交信息本身，不要输出额外解释。
### 4.3 验证 Skill 是否生效 回到项目根目录，启动 Claude Code： ```bash claude先暂存一些改动，然后对 Claude 说：
帮我根据暂存区的改动生成一条 commit messageClaude 会读取git-commit这个 Skill，执行git diff --cached，并按照你定义的格式输出提交信息。
如果 Claude 没有自动调用，可以直接点名 Skill，比如「使用 git-commit 技能生成提交信息」。
5. 深入实战：带脚本的 Skill
纯指令型 Skill 适合流程性任务，但当 Skill 需要执行确定性逻辑（解析、统计、校验）时，就应该引入脚本。脚本让 Claude 从「手动推理」变为「调用你的可信代码」，结果更稳定。
以「接口文档生成」为例，我们创建一个api-doc-genSkill。
5.1 创建目录与脚本
mkdir-p.claude/skills/api-doc-gen/scriptscd.claude/skills/api-doc-gen创建脚本scripts/extract_routes.py，用于从一个 Node.js Express 项目中提取路由定义：
#!/usr/bin/env python3""" 从 Express / Fastify 等项目源码中提取路由端点信息。 用法: python extract_routes.py <项目根目录> """importreimportsysfrompathlibimportPathdefextract_express_routes(content:str,file_path:Path)->list[dict]:"""提取 Express 风格路由: app.get('/path', handler)"""routes=[]pattern=re.compile(r"(?:app|router)\.(get|post|put|patch|delete)\("r" ['\"]([^'\"]+)['\"]")formatchinpattern.finditer(content):method=match.group(1).upper()path=match.group(2)routes.append({"method":method,"path":path,"file":str(file_path)})returnroutesdefmain():iflen(sys.argv)<2:print("用法: python extract_routes.py <项目根目录>")sys.exit(1)root=Path(sys.argv[1])all_routes=[]forfile_pathinroot.rglob("*.js"):if"node_modules"infile_path.parts:continuecontent=file_path.read_text(encoding="utf-8",errors="ignore")all_routes.extend(extract_express_routes(content,file_path))print(f"共发现{len(all_routes)}个路由端点:\n")forrouteinall_routes:print(f"-{route['method']:6s}{route['path']:30s}({route['file']})")if__name__=="__main__":main()5.2 编写 SKILL.md
--- name: api-doc-gen description: 从项目源码中提取 API 端点，并生成结构化的接口文档。在用户要求生成 API 文档、整理接口列表、梳理后端路由时使用。 --- # API 文档生成技能 ## 前置条件 - 项目的 API 采用 Express 或 Fastify 风格定义路由。 - 已安装 Python 3.9 及以上版本。 ## 执行步骤 1. 运行路由提取脚本： ```bash python3 scripts/extract_routes.py <项目根目录>根据脚本输出的路由列表，逐一阅读对应源码文件，补充以下信息：
- 功能说明
- 请求参数（query / body / path）
- 响应示例与状态码
按以下 Markdown 结构输出文档：
## 接口列表 | 方法 | 路径 | 说明 | |------|------|------| | GET | /users | 获取用户列表 | ### GET /users - **功能**：... - **请求参数**：... - **响应示例**：...约束
- 只输出接口文档，不要改动任何源码。
- 如果脚本无法识别某些路由，请在文档末尾单独列出并提示人工确认。
### 5.3 使用带脚本的 Skill 在 Claude Code 中说： ```text 使用 api-doc-gen 技能，为当前项目生成 API 文档Claude 会执行scripts/extract_routes.py，拿到确定性路由列表，再结合源码阅读补充细节，最终输出完整文档。
脚本的价值在于：路由提取这类「模式匹配」工作由脚本精准完成，Claude 专注于需要语义理解的文档撰写，两者各司其职。
6. 实战案例：代码审查助手
下面构建一个更完整的code-reviewerSkill，它结合了检查清单、静态分析脚本和报告模板，展示 Skills 的渐进式加载能力。
6.1 目录结构
.claude/skills/code-reviewer/ ├── SKILL.md ├── scripts/ │ └── analyze.sh ├── references/ │ └── checklist.md └── assets/ └── report-template.md6.2 静态分析脚本 scripts/analyze.sh
#!/usr/bin/env bash# 对传入的目录执行基础的静态检查。# 用法: ./analyze.sh <目标目录>set-euopipefailTARGET="${1:-.}"echo"=== 待审查文件列表 ==="find"$TARGET"-typef\(-name"*.js"-o-name"*.ts"-o-name"*.py"\)\-not-path"*/node_modules/*"-not-path"*/venv/*"|sortecho""echo"=== TODO / FIXME 标记 ==="grep-rn--include="*.js"--include="*.ts"--include="*.py"\-E"TODO|FIXME|HACK""$TARGET"||echo"未发现 TODO/FIXME 标记"echo""echo"=== 可疑的硬编码密钥 ==="grep-rniE--include="*.js"--include="*.ts"--include="*.py"\-E"(password|secret|api_key|token)[[:space:]]*=""$TARGET"||echo"未发现可疑硬编码密钥"将该脚本设为可执行：
chmod+x scripts/analyze.sh6.3 检查清单 references/checklist.md
# 代码审查检查清单 ## 正确性 - [ ] 是否存在数组越界、空指针、除零等边界问题 - [ ] 异步逻辑是否正确处理了 race condition - [ ] 错误处理是否覆盖了异常分支 ## 安全性 - [ ] 用户输入是否做了校验和转义 - [ ] SQL 是否使用参数化查询 - [ ] 日志中是否包含敏感信息 ## 可维护性 - [ ] 函数是否遵循单一职责 - [ ] 是否存在重复代码 - [ ] 命名是否清晰表达意图6.4 报告模板 assets/report-template.md
# 代码审查报告 ## 基本信息 - **审查文件**： - **审查时间**： - **总体结论**：（通过 / 需修改 / 存在阻塞问题） ## 问题列表 ### 1. [严重程度] 问题标题 - **所在位置**： - **问题描述**： - **修复建议**： ## 优点 ## 改进建议6.5 组装 SKILL.md
--- name: code-reviewer description: 对指定代码进行质量、安全性和规范性审查。在用户要求审查代码、检查 PR、评估代码质量时使用。 --- # 代码审查技能 ## 执行步骤 1. 运行静态分析脚本： ```bash ./scripts/analyze.sh <目标目录>- 阅读
references/checklist.md，逐项核对目标代码。 - 结合脚本输出与人工分析，按照
assets/report-template.md的模板生成审查报告。
审查原则
- 优先报告「会产生实际危害」的问题，其次是可维护性问题。
- 每条问题必须给出所在文件和修复建议，禁止笼统表述。
- 对存疑项使用「待确认」标记，不要主观臆断。
使用时，在 Claude Code 中指定文件夹或文件： ```text 用 code-reviewer 技能审查 src/services 下的代码Claude 的执行链路为：运行analyze.sh→ 读取checklist.md→ 读取审核模板 → 生成最终报告。references/中的内容只有在执行该 Skill 时才会被加载，不会平白占用日常对话的上下文窗口。
7. 实战案例：SQL 审核技能（渐进式加载参考）
再看一个需要海量领域知识的场景。假设团队有严格的数据库规范，这些规范很长，不可能每次对话都塞给 Claude。解决方案就是把规范放进references/，让 Claude 在需要时按主题加载。
7.1 目录结构
.claude/skills/sql-reviewer/ ├── SKILL.md └── references/ ├── index.md # 参考资料的索引，帮助 Claude 决定读哪份 ├── index-rules.md # 索引设计规范 ├── sql-rules.md # SQL 书写规范 └── migration-rules.md # 数据库迁移规范7.2 references/index.md 的作用
# SQL 审核参考索引 根据审查内容选择对应文档： - 涉及建表、字段类型、主外键 → 阅读 `index-rules.md` - 涉及 SELECT/INSERT/UPDATE/DELETE 语句 → 阅读 `sql-rules.md` - 涉及表结构变更、数据迁移 → 阅读 `migration-rules.md`7.3 SKILL.md 示例
--- name: sql-reviewer description: 审查 SQL 语句、表结构设计和数据迁移脚本是否符合团队数据库规范。在用户要求审查 SQL、检查建表语句、评估索引设计时使用。 --- # SQL 审核技能 ## 执行步骤 1. 先阅读 `references/index.md`，确定需要加载哪份规范文档。 2. 只加载与待审查内容相关的规范，不要一次加载全部。 3. 逐条对照规范，标记违规项并给出修改后的 SQL。 ## 输出格式 每条问题按以下格式输出： - **违规项**：引用具体规范条款 - **原始语句**：待审查的 SQL 片段 - **修改建议**：给出可执行的替代语句这个案例展示了渐进式加载的关键做法：先用轻量的index.md帮助模型决定读哪份详细文档，而不是把全部规范一次性塞进上下文，从而在「信息完整」和「上下文节约」之间取得平衡。
8. Skill 的管理与组织
随着
