Claude Code Skills 完全入门指南
很多人用 Claude Code 的时候，会碰到两个烦心事。一个是每次都要重复说同样的话，比如告诉它用哪种代码规范。另一个是通用AI不太懂你项目的特殊情况。Claude 的 Skills 功能正好能解决这两个问题。
说白了，Skills 就是给 Claude 准备的说明书。你提前写好一份文件放在 Skills 目录里，告诉 Claude 碰到什么情况该怎么做。等真的遇到那种情况，它自己就会照着做，不用你每次都说一遍。
这篇文章从头开始讲，看完你会明白这几件事：
Skills 怎么工作的
SKILL.md 文件怎么写
技能文件放哪，优先级怎么排
怎么往技能里传参数
内置的几个技能怎么用
怎么把技能分享给别人
第一章 什么是 Skills
如果你刚开始用 Claude Code，可以先这样理解：Skills 就是给 Claude 定制的专项技能包。让它学会某一类知识或者工作流程，处理相关任务的时候就更专业。
打个比方。你雇了一个特别聪明的助理，但他对你的公司、项目、习惯都不了解。Skills 就是你给他准备的培训手册。告诉他你们团队用什么技术、代码怎么写、怎么部署。有了这个手册，助理马上就能上手，不用每次都从头解释。
1.1 Skills 解决了什么问题
没有 Skills 的时候，你会碰到这些麻烦。
每次开新会话都要重新告诉 Claude 用 TypeScript，遵守 Airbnb 规范。换一个项目，Claude 完全不知道这个项目的规矩。部署、审查、提交这些操作，要一步步手动提示。团队积累的经验只存在人脑子里，没法传给AI。
Skills 就是为解决这些问题做的。你把常用知识和流程写成配置文件，Claude 需要的时候自己加载用。
1.2 几个核心概念
SKILL.md 是技能的核心文件，里面写指令和配置。可以理解成岗位说明书。
frontmatter 是 SKILL.md 顶部用三个短横线包起来的YAML配置区域，可以理解成档案封面。
斜杠命令就是用 /skill-name 这种方式调用技能，相当于快捷拨号。
自动触发是Claude自己根据情况判断要不要加载技能，相当于情景感应。
支持文件是技能目录里的额外文件，比如模板、脚本，可以理解成工具箱。
1.3 Skills 和其他功能有什么区别
Claude Code 有几个容易搞混的概念。
CLAUDE.md 是项目级的持久记忆。Skills 是可复用的能力包，不只是记东西。
自定义命令是单个文件的斜杠命令。Skills 是命令的超集，支持目录结构，功能更多。
子代理是独立执行任务的AI实例。Skills 可以在子代理里跑，也可以单独跑。
插件是可分发扩展包。插件里面可以包含 Skills。
向后兼容要注意一下。Skills 和旧版自定义命令完全兼容。你在 .claude/commands/deploy.md 创建的命令，和在 .claude/skills/deploy/SKILL.md 创建的技能，效果一样，/deploy 命令都能用。已有的配置不用改。
1.4 技能怎么运行的
了解背后的运行机制，能帮你写出更好用的技能。
Claude 启动的时候，会扫描已经安装的技能目录，把每个技能的名字和描述记下来。只有用户的问题符合某个技能的触发条件时，Claude 才会去读那个技能的 SKILL.md 文件，把内容加载进来。
如果指令里提到了别的文件，比如参考文档、示例模板，Claude 也会自己去读。如果提到要执行脚本，Claude 直接跑脚本拿结果，不会把脚本源码也加载进去。这种逐步加载的方式，让技能可以带很多参考内容，但不会一次占满整个对话窗口。
第二章 快速上手
理论说够了，动手最重要。这一章我们从零开始，做一个能用的技能。
2.1 技能的文件结构
一个技能就是一个文件夹。最简单的形式只需要一个文件。
my-skill/
├── SKILL.md # 必需，核心文件
├── template.md # 可选，模板文件
├── examples/
│ └── sample.md # 可选，示例
└── scripts/
└── helper.sh # 可选，脚本SKILL.md 是唯一必需的文件。其他的看需要再加。
2.2 SKILL.md 的结构
每个 SKILL.md 分成两部分。
最上面是两个短横线包起来的 frontmatter，用 YAML 格式，写技能的元信息。
---
name: my-skill
description: 描述这个技能的作用和触发时机
---然后下面是正文，写 Markdown 格式的指令。
当 Claude 调用这个技能的时候，就会按照正文里的指令做。
2.3 动手做一个解释代码的技能
我们来做一个代码讲解技能，让 Claude 解释代码的时候总用类比和图示。
第一步，创建技能目录。个人技能放在 ~/.claude/skills/ 下面，对所有项目都有效。
mkdir -p ~/.claude/skills/explain-code第二步，编写 SKILL.md。创建文件 ~/.claude/skills/explain-code/SKILL.md。
---
name: explain-code
description: 用类比和图示解释代码原理。当用户问这段代码是什么意思、这个函数怎么工作的时候自动触发。
---
解释代码的时候，必须包含下面四个部分。
1. 生活类比：用日常例子打比方
2. ASCII 图示：用字符画结构或者流程
3. 逐步解析：一行一行解释代码做了什么
4. 常见误区：指出最容易搞错的地方
语气要通俗，适合初学者。第三步，测试技能。技能做好以后，有两种方式触发。
自动触发：直接问 Claude 相关问题。比如在聊天里问这段 Promise 代码是什么意思。
手动触发：用斜杠命令。比如 /explain-code src/auth/login.ts
Claude 回答的时候，就会按照你的指令，必然包含类比和图示。
验证技能有没有加载成功，可以在 Claude Code 里问 What skills are available，看看你的技能在不在列表里。
第三章 技能放哪
放的位置不一样，作用范围也不一样。是只给自己用，还是整个项目用，还是团队一起用。
3.1 四个存放位置
企业级，通过管理配置下发。所有组织成员都能用。适合公司统一规范和策略。
个人级，路径是 ~/.claude/skills/。你所有的项目都能用。适合个人习惯和通用工具。
项目级，路径是 .claude/skills/。只在当前项目里用。适合项目特定知识和团队协作。
插件内，路径是 /skills/。插件启用的地方就能用。适合随插件一起分发。
3.2 优先级和同名冲突
如果多个地方有同名的技能，优先级从高到低是：企业级高于个人级，个人级高于项目级。
插件里的技能用 plugin-name:skill-name 这种命名方式，不会和其他级别的冲突。
3.3 Monorepo 子目录自动发现
如果你的项目是 Monorepo 结构，Claude Code 会自动发现子目录里的技能。比如你在编辑 packages/frontend/ 里面的文件，Claude Code 会自动找 packages/frontend/.claude/skills/ 里的技能。
my-monorepo/
├── .claude/skills/ # 根目录技能，所有子包都能用
│ └── deploy/
├── packages/
│ ├── frontend/
│ │ └── .claude/skills/ # 前端专属技能
│ │ └── react-patterns/
│ └── backend/
│ └── .claude/skills/ # 后端专属技能
│ └── api-conventions/3.4 --add-dir 的特殊行为
用 --add-dir 参数添加额外目录的时候，这个目录下面的 .claude/skills/ 会被自动加载。这是 Skills 特有的规则，其他配置比如 subagents、commands 不会加载。
这个特性很适合共享技能库。
claude --add-dir /path/to/shared-skills-repo而且支持热更新。在会话里改了这些技能文件，不用重启 Claude Code，修改马上生效。
第四章 Frontmatter 配置详解
Frontmatter 是控制技能行为的控制面板。掌握这些配置，才能真正用好 Skills。
4.1 完整配置列表
name，不是必需的，默认用目录名。这是技能显示名，会生成 /name 斜杠命令。只能用小写字母、数字、连字符，最长64个字符。
description，推荐写。Claude 靠这个决定要不要自动加载。重要的关键词放前面，因为超过250个字符会被截断。
argument-hint，不是必需的。自动补全的时候显示的参数提示，比如 [filename] [format]。
disable-model-invocation，不是必需的，默认是 false。设为 true 的时候，只有你能手动触发，Claude 不会自动加载。
user-invocable，不是必需的，默认是 true。设为 false 的时候，从斜杠菜单里隐藏，只让 Claude 自己调用。
allowed-tools，不是必需的。这个技能激活的时候，Claude 可以不用问你直接用的工具列表。
model，不是必需的，继承会话的设置。这个技能激活的时候用的模型。
effort，不是必需的，继承会话的设置。努力级别，有 low、medium、high、max。
context，不是必需的，默认是内联。设为 fork 的时候，在隔离的子代理里运行。
agent，不是必需的。和 context: fork 配合，指定子代理类型。
hooks，不是必需的。技能生命周期钩子的配置。
paths，不是必需的。Glob 模式，限定技能只在特定文件类型时激活。
shell，不是必需的，默认是 bash。用于感叹号加反引号这种命令注入的 shell，可以选 powershell。
4.2 重点字段详解
description 是整个 frontmatter 里最重要的字段。Claude 靠它判断什么时候该加载这个技能。
写好 description 有几个原则。最重要的触发关键词放最前面，因为超过250字符会被截断。要说明什么时候用，比如当用户问什么的时候使用。不要写得太宽泛，太宽泛会导致技能频繁触发，影响性能。
反面例子是帮助 React 开发，太模糊了。正面例子是 React 组件性能优化指导。当代码包含 useEffect、useMemo、useCallback，或者用户问组件卡顿、重复渲染问题的时候使用。
disable-model-invocation 和 user-invocable 这两个字段控制谁能触发技能，很多人搞混。
默认情况下，你能用斜杠调用，Claude 能自动调用，技能出现在斜杠菜单里。
如果设了 disable-model-invocation: true，你能用斜杠调用，Claude 不能自动调用，技能还出现在菜单里。
如果设了 user-invocable: false，你不能用斜杠调用，Claude 能自动调用，技能不在菜单里。
disable-model-invocation: true 适合有副作用的操作，比如部署、发消息，你不希望 Claude 自己执行。
user-invocable: false 适合背景知识型的技能，比如老系统的说明。Claude 应该知道，但这本身不是一个有意义的命令。
paths 可以让技能只在处理特定文件的时候激活，避免影响不相关的任务。
---
name: react-patterns
description: React 最佳实践
paths: "**/*.tsx,**/*.jsx"
---这个技能只在处理 React 文件的时候，Claude 才会考虑加载。
effort 可以控制思考深度。可以为特定技能设不同的思考强度，在速度和质量之间找平衡。注意 max 级别只有 Claude Opus 4.6 能用。
---
name: deep-review
description: 深度代码审查
effort: max
---第五章 变量和动态内容
静态指令有时候不够用。你可能需要把用户输入的内容传给技能，或者注入实时的数据。Skills 提供了两种办法。
5.1 参数变量
用户调用 /skill-name 的时候可以传参数，技能里面用变量引用。
$ARGUMENTS 代表所有参数，合并成一个字符串。比如 /fix-bug 1234 传进来就是 1234。
$ARGUMENTS[N] 代表第 N 个参数，从 0 开始数。$ARGUMENTS[0] 就是第一个参数。
$0、$1、$2 是 $ARGUMENTS[N] 的简写。
${CLAUDE_SESSION_ID} 是当前会话的ID，可以用来写日志或者给临时文件起名字。
${CLAUDE_SKILL_DIR} 是技能目录的绝对路径，引用技能自带的脚本时用。
看一个单参数的例子。
---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---
修复 GitHub Issue #$ARGUMENTS，按下面步骤做。
1. 读 Issue 描述
2. 分析根本原因
3. 写修复代码
4. 写测试
5. 提交代码执行 /fix-issue 42 的时候，Claude 收到的指令就变成了修复 GitHub Issue #42，按下面步骤做。
再看一个多参数的例子。
---
name: migrate-component
description: 把组件从一个框架迁移到另一个框架
---
把 $0 组件从 $1 迁移到 $2。保留所有现有功能和测试，不要改行为。执行 /migrate-component SearchBar React Vue 的时候，Claude 收到把 SearchBar 组件从 React 迁移到 Vue。
5.2 Shell 命令注入
用感叹号加反引号这种写法，可以在技能发给 Claude 之前，先执行一段 Shell 命令，把输出注入到技能内容里。
重要区别：这不是 Claude 执行命令，而是 Claude Code 在发技能给 Claude 之前做预处理。Claude 只看到最后输出的文字，不知道有命令被执行过。
---
name: pr-summary
description: 总结当前 Pull Request 的变更
context: fork
allowed-tools: Bash(gh *)
---
## PR 上下文
- 变更差异：!`gh pr diff`
- PR 评论：!`gh pr view --comments`
- 修改文件：!`gh pr diff --name-only`
## 你的任务
请总结这个 PR 的主要变更、影响范围和风险。如果是多行命令，可以用三个反引号加感叹号的代码块。
## 运行环境
```!
node --version
npm --version
git log --oneline -5管理员可以在设置里加 disableSkillShellExecution 为 true 来禁用这个功能，适合安全要求高的环境。被禁用的时候，注入的地方会替换成一行说明文字。
第六章 支持文件
单个 SKILL.md 适合简单任务，但复杂功能需要多个文件配合。
6.1 为什么需要支持文件
有几个情况，单文件会遇到麻烦。详细的API文档、参考规范如果都塞进一个文件，每次触发技能都全量加载，占很多 context。代码审查报告、技术文档有固定格式，需要模板文件。生成图表、处理数据这些任务，需要 Python 或 Shell 脚本。
解决办法是把这些内容拆到独立文件里，在 SKILL.md 里引用，让 Claude 按需加载。
6.2 推荐目录结构
code-review/
├── SKILL.md # 核心指令，控制在500行以内
├── checklist.md # 详细清单，按需加载
├── templates/
│ └── report.md # 报告模板
├── examples/
│ ├── good-example.ts # 好例子
│ └── bad-example.ts # 坏例子
└── scripts/
└── complexity.py # 计算复杂度的脚本6.3 在 SKILL.md 里引用支持文件
在 SKILL.md 里要明确告诉 Claude 每个文件是干什么的，什么时候加载。
---
name: code-review
description: 全面的代码审查，包含安全、性能、可维护性检查
---
执行代码审查，重点看安全、性能、可读性。
## 附加资源
- 详细清单：见 [checklist.md](checklist.md)，做审查的时候加载
- 报告模板：见 [templates/report.md](templates/report.md)，写报告的时候用
- 跑复杂度分析：python ${CLAUDE_SKILL_DIR}/scripts/complexity.py
## 输出要求
用模板格式出审查报告。好的做法是把 SKILL.md 控制在500行以内，详细的参考资料放到独立文件里。Claude 真正需要的时候才会加载它们，节省 context 空间。
6.4 实战案例
下面是一个完整的例子，做一个能生成 HTML 图表的技能。
目录结构：
codebase-visualizer/
├── SKILL.md
└── scripts/
└── visualize.pySKILL.md 的内容：
---
name: codebase-visualizer
description: 生成代码库的交互式 HTML 树状图。
探索新代码库、了解项目结构的时候用。
allowed-tools: Bash(python *)
---
# 代码库可视化
运行可视化脚本：
```bash
python ${CLAUDE_SKILL_DIR}/scripts/visualize.py .这会在当前目录生成 codebase-map.html 并在浏览器里打开。
注意 ${CLAUDE_SKILL_DIR} 的用法。不管当前工作目录在哪，这个变量始终指向技能文件所在的目录，能保证脚本路径正确。
## 第七章 高级用法
掌握基础之后，这一章介绍两个让 Skills 更强大的高级功能：在独立子代理里运行技能，以及精细控制工具权限。
### 7.1 在子代理里运行技能
context: fork 让技能在隔离的子环境里执行，不影响主对话。就像派一个特种兵去完成特定任务，做完回来汇报结果。
什么时候用 context: fork？任务独立性强，需要大量探索，不应该干扰主对话。任务需要只读的工具集。PR分析、代码库扫描这些不需要对话历史的任务。
看一个深度研究技能的例子。
```yaml
---
name: deep-research
description: 对指定主题深入研究，分析代码库
context: fork
agent: Explore
---
深入研究：$ARGUMENTS
1. 用 Glob 和 Grep 找到相关文件
2. 读代码并分析
3. 总结发现，附上具体文件引用可用的内置代理类型有几种。
Explore 代理只用只读工具，适合代码库研究、写文档。
Plan 代理用读取和规划工具，适合任务拆解、架构设计。
general-purpose 代理用全套工具，适合通用任务。
自定义代理由 .claude/agents/ 定义，适合项目特定的专属代理。
7.2 工具访问控制
allowed-tools 可以限制工具。在技能激活期间，可以限制 Claude 只用某些工具，这对只读技能或者安全敏感的操作很有用。
---
name: safe-reader
description: 只读模式，不改任何文件
allowed-tools: Read Grep Glob
---
在只读模式下分析代码...多个工具可以用空格隔开，也可以用 YAML 列表的写法。
allowed-tools:
- Read
- Grep
- Bash(gh *)
- Bash(python *)除了在单个技能里控制，还可以在权限配置里全局管理哪些技能 Claude 能调用。在 /permissions 里可以禁用所有技能，或者只允许某些技能，或者禁止某些技能。
7.3 扩展思维模式
在技能内容里任意位置写上 ultrathink 这个词，就能激活 Claude 的深度思考模式，适合需要复杂推理的技能。
---
name: architecture-review
description: 深度架构审查
effort: max
---
对这个系统做架构审查。ultrathink
分析可扩展性、安全性、可维护性、性能。第八章 内置技能
Claude Code 自带几个高质量的内置技能，可以直接用，不用配置。
8.1 内置技能列表
/batch 后面跟指令。功能是并行大规模重构，自动拆任务，为每个子任务建独立分支并行处理。比如把 src 下所有组件从类组件迁移到函数组件。
/claude-api 加载 Claude API 参考文档，支持 Python、TS、Go 等8种语言。代码里 import anthropic 的时候会自动触发。
/debug 后面跟描述。启用 debug 日志，分析当前会话的调试信息。比如问为什么这个工具调用总是失败。
/loop 后面跟间隔和提示。按间隔重复执行提示，适合监控类任务。比如每5分钟检查一次部署有没有完成。
/simplify 后面跟焦点。并行启动三个代理审查最近改的代码，发现并修问题。比如专注于内存效率。
8.2 /batch 详解
/batch 是内置技能里最厉害的。它能把大型重构任务自动化。
工作流程是这样的。Claude 先研究代码库，搞明白任务范围。然后把工作拆成5到30个独立的小任务。接着把计划展示给你，等你确认。确认之后，为每个小任务建独立的 git worktree。然后并行启动多个后台代理，各自处理一个小任务。每个代理做三件事：实现、测试、提交、开 Pull Request。
使用 /batch 需要 git 仓库环境。适合大型、相对独立的批量修改任务，不适合需要严格按顺序来的变更。
第九章 分享技能
好的技能应该分享出去，不只自己用。
9.1 三种分享方式
第一种，用 Git 版本控制做团队协作。把项目级技能提交到代码仓库，团队成员 clone 下来就能用。
git add .claude/skills/
git commit -m "add: code-review and deploy skills"
git push所有团队成员的 Claude Code 都会自动加载这些技能，不用单独配置。
第二种，打包成插件。如果你的技能还有其他配置配套，比如 MCP 服务器、钩子，可以打包成插件。
my-plugin/
├── claude-plugin.json # 插件清单
├── skills/
│ ├── deploy/
│ └── review/
└── hooks/
└── post-commit.sh第三种，企业级管理配置。企业版用户，管理员可以通过管理配置文件给所有成员统一下发技能。新成员入职就自动有团队的技能集。
9.2 Agent Skills 开放标准
Anthropic 已经把 Skills 发布成开放标准了，网址是 agentskills.io。这意味着同一个 SKILL.md 可以在 Claude Code 和其他支持这个标准的 AI 工具里用。社区可以贡献和分享通用的技能包。以后更多工具支持这个标准，你写的技能也不会过时。
第十章 故障排查
技能不按预期工作？这一章给一些排查方法和经验总结。
10.1 常见问题和解决办法
技能没有触发。先确认技能文件在不在，路径和文件名对不对，注意 SKILL.md 大小写不能错。然后在 Claude Code 里问 What skills are available，看技能在不在列表里。检查 description 有没有包含用户可能用的关键词。试试手动触发 /skill-name，确认技能语法没错。检查是不是设了 disable-model-invocation: true，如果设了，Claude 不会自动触发。
技能触发太频繁。让 description 更具体，减少容易误触的关键词。或者设 disable-model-invocation: true，改成手动触发。也可以用 paths 字段限制文件类型。
description 被截断。症状是技能名字在列表里，但关键的触发词丢了，导致 Claude 匹配不上。解决办法是把最重要的触发关键词挪到 description 最前面。每个技能的 description 严格控制在250字符以内，这是硬性限制。如果需要增加总预算，可以设环境变量 export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000。
Shell 注入命令失败。先在终端手动跑一下命令，确认命令本身是对的。检查技能目录里的脚本文件权限，用 chmod +x scripts/xxx.sh 加上执行权限。确认 disableSkillShellExecution 没有被管理员禁用。
10.2 技能编写建议
文件大小方面，SKILL.md 控制在500行以内，不要把所有内容都堆在一个文件里。
description 要把关键词放前面，具体描述使用场景，少于250字符。不要写模糊的描述，比如帮助开发。
有副作用的操作要设 disable-model-invocation: true，不要让 Claude 自己触发部署、发消息这些操作。
工具权限要用 allowed-tools 给最小权限，不要给只读技能分配写的权限。
脚本路径要用 ${CLAUDE_SKILL_DIR} 引用技能自带的脚本，不要用绝对路径。
技能范围要一个技能只做一件事，不要把不相关的功能塞在一起。
版本控制要把项目技能提交到 git，不要让技能只存在自己电脑上。
10.3 开发流程建议
这是一个验证过的技能开发流程。
先明确需求，写下你想让 Claude 做什么，以及什么时候触发。然后从简单开始，先写最小可用的版本，只有 name、description 和核心指令。接着测试触发，自动触发和手动触发都试一遍。然后收集反馈，实际用几天，看看哪里不符合预期。再迭代优化，根据反馈调整 description 和指令细节。需要的时候再加支持文件，比如模板、示例、脚本，不要过度设计。最后，好的技能提交到代码库，和团队分享。
附录 Frontmatter 速查卡
---
# 基本信息
name: skill-name # 技能名，生成 /skill-name 命令
description: > # Claude 判断触发的依据，少于250字符
关键词放前面，描述什么时候用。
# 调用控制
disable-model-invocation: false # true 表示只能手动斜杠调用
user-invocable: true # false 表示从菜单隐藏，只让 Claude 自己调
# 工具和模型
allowed-tools: Read Grep Glob # 不用审批的工具，空格隔开
model: claude-sonnet-4-6 # 覆盖默认模型
effort: medium # low / medium / high / max
# 执行环境
context: fork # 在隔离的子代理里运行
agent: Explore # 指定子代理类型
# 激活范围
paths: "**/*.tsx,**/*.jsx" # 只在匹配的文件类型时激活
# 其他
argument-hint: "[issue-number]" # 自动补全提示
shell: bash # bash 或者 powershell
---官方文档是 Claude Code Skills Documentation。开放标准可以看 agentskills.io。
本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！