Claude Code Skill 系统完整教程：从创建到调用，一篇讲清楚

大家好，我是 Immerse

专注分享 AI 玩法、独立开发与AI 出海的 AGI 实践者

用 Claude Code 一段时间后，你会发现它其实很"健忘"——每次对话都从零开始，你的项目规范、提交格式、部署步骤，每次都得重新交代一遍。

Skills 就是解决这个问题的。说白了就是个 Markdown 文件，你把"Claude 该怎么做某件事"写进去，之后用 /skill-name 直接调用，或者 Claude 觉得合适的时候自己加载进来。

如果你用过 .cursorrules 或者 CLAUDE.md，可以这样理解：CLAUDE.md 是全局规范，告诉 Claude 这个项目是什么；Skill 是操作手册，告诉 Claude 怎么完成某个具体任务。一个管背景，一个管动作。

先跑一个最简单的

前置条件：已安装 Claude Code，能正常用 / 命令。

1. 建目录：

mkdir -p ~/.claude/skills/commit

1. 创建 ~/.claude/skills/commit/SKILL.md，内容如下：

---
name:commit
description:根据stagedchanges生成commitmessage并提交
disable-model-invocation:true
allowed-tools:
-Bash(git*)
---

根据当前stagedchanges生成commitmessage并提交：

1.执行`gitdiff--cached`看改了什么
2.生成commitmessage，格式：type(scope):description
3.执行`gitcommit-m"message"`

如果没有staged内容，提示用户先`gitadd`。

1. 在任意 git 仓库里试：

git add src/auth.ts

然后在 Claude Code 里输入：

/commit

Claude 会先读 diff，然后给你一个 message，比如：

feat(auth): add token expiry validation

确认后直接提交。如果你 staged 了空内容，它会说"没有 staged changes，请先 git add"，不会乱跑。

这就是一个完整可用的 Skill。接下来把每个部分拆开讲。

SKILL.md 的结构

每个 Skill 就是一个目录，里面有一个 SKILL.md：

commit/
└── SKILL.md

SKILL.md 分两部分：YAML 头信息 + markdown 正文。

---
name: commit
description: 做什么，什么时候触发
---

这里是 Claude 的具体操作指令

name 决定 / 命令名。description 是 Claude 判断"要不要自动加载这个 Skill"的依据——写清楚什么场景下触发，Claude 才能准确匹配。

正文就是普通 Markdown，你想让 Claude 怎么做，就怎么写。步骤、规范、约束，都可以放进去。

头信息配置

name 和 description

name 只支持小写字母、数字和连字符，最长 64 个字符。不填的话用目录名。

description 是整个 Skill 系统最重要的字段。Claude 会把所有 Skill 的 description 预加载进上下文，用来判断该不该触发某个 Skill。所以要写清楚"什么时候用"，不然 Claude 不知道该用还是不该用。

坏的 description：

description: 帮助用户

好的 description：

description: 当用户需要提交代码时，根据 staged changes 生成 commit message 并提交。用户输入 "commit"、"提交"、"git commit" 时触发。

allowed-tools

Skill 激活时，Claude 能用哪些工具不用你每次手动授权，allowed-tools 直接配好：

allowed-tools:
  -Read
-Write
-Bash(git*)
-Bash(npmrun*)

Bash(git *) 表示只允许执行 git 开头的命令。Bash(npm run *) 只允许 npm run 开头的。这样就算 Claude 想执行别的命令，它也跑不了。

如果不配这个字段，Skill 激活时用的是你的全局权限设置，每个操作都可能需要手动授权。

disable-model-invocation

有些 Skill 不想让 Claude 自动触发——比如部署、发邮件、推代码到远端，这些有副作用的操作，你肯定想自己控制时机。加这个字段：

disable-model-invocation: true

加了之后，这个 Skill 的 description 也不会出现在 Claude 的上下文里。只有你手动 /skill-name 才会触发，Claude 不会自己跑。

user-invocable

反过来的情况：有些 Skill 只想让 Claude 自动加载，不想暴露给用户当命令用，比如一些背景知识类的参考文件：

user-invocable: false

加了之后它不会出现在 / 命令菜单里，但 Claude 判断相关时还是会加载。

两个字段组合起来：

argument-hint

如果你的 Skill 需要参数，可以加个提示，在输入 / 时会显示出来：

argument-hint: [issue-number]

这样用户输入 /fix-issue 就能看到提示，知道后面要跟什么。

传参数给 Skill

Skill 里用 $ARGUMENTS 接收用户传的参数：

---
name:fix-issue
description:根据GitHubissue号修复bug
disable-model-invocation:true
argument-hint:[issue-number]
---

修复GitHubissue$ARGUMENTS：

1.读取issue描述，理解需求
2.找到相关代码，实现修复
3.写测试
4.生成commitmessage，格式：fix(scope):description(closes#$ARGUMENTS)

执行 /fix-issue 42，Claude 收到的就是"修复 GitHub issue 42"和"closes #42"。

多个参数用 ARGUMENTS[0]、ARGUMENTS[1]，或者简写 0、1：

---
name: migrate-component
description: 将组件从一个框架迁移到另一个
---

将 $0 组件从 $1 迁移到 $2，保留所有现有行为和测试。

执行 /migrate-component SearchBar React Vue，Claude 收到"将 SearchBar 组件从 React 迁移到 Vue"。

Skill 放在哪

个人 Skill 优先级高于项目 Skill——同名时，个人的覆盖项目的。

项目 Skill 适合放团队共用的规范，提交到版本控制里，所有人都能用。个人 Skill 放你自己的偏好，比如你惯用的提交格式、你习惯的代码审查方式。

.claude/commands/ 下的文件也照样工作，跟放在 .claude/skills/ 里效果一样——这是为了向前兼容旧用法，新建的建议放在 skills/ 目录。

加支持文件

Skill 不只能有一个 SKILL.md，可以带着一堆支持文件：

deploy/
├── SKILL.md           # 主指令
├── checklist.md       # 部署检查清单
├── rollback.md        # 回滚步骤
└── scripts/
    └── health-check.sh

在 SKILL.md 里引用这些文件，Claude 知道它们存在，需要时会去读：

## 参考资料

- 部署前检查：[checklist.md](checklist.md)
- 回滚步骤：[rollback.md](rollback.md)

这样 SKILL.md 保持简洁，复杂的参考内容按需加载，不会每次都塞满上下文。官方建议 SKILL.md 控制在 500 行以内，长的拆出去放支持文件。

注入动态内容

有些 Skill 需要实时数据，比如当前 PR 的 diff、最新的部署状态。用 !`命令` 语法，Skill 激活时先跑命令，把输出插进去：

---
name:pr-summary
description:总结当前PR的改动
context:fork
allowed-tools:
-Bash(gh*)
---

## PR 信息
-diff:!`ghprdiff`
-评论:!`ghprview--comments`
-改动文件:!`ghprdiff--name-only`

用中文总结这个PR改了什么，有什么风险点。

执行时，三个 !`...` 先跑，把输出填进去，Claude 收到的是包含实际 diff 内容的完整 prompt。这是预处理，不是 Claude 执行命令，Claude 只看到最终结果。

在子 Agent 里跑

有些 Skill 适合在独立上下文里跑，不污染主对话。加 context: fork：

---
name:code-audit
description:审查代码库，找出潜在的安全问题和性能瓶颈
context:fork
agent:Explore
allowed-tools:
-Read
-Grep
-Glob
---

审查$ARGUMENTS目录下的代码：

1.用Glob找出所有.ts和.js文件
2.检查是否有明显的SQL注入、XSS风险
3.找出可能的性能瓶颈（比如循环里的async/await）
4.给出具体文件和行号的报告

context: fork 会起一个独立的子 Agent，用 SKILL.md 内容作为它的任务。完成后把结果摘要返回到主对话，不会把大量代码审查输出全堆进来。

agent 字段指定用什么类型的子 Agent：

• Explore：只读，擅长搜索和分析代码库
• Plan：规划型，适合做架构设计和方案
• general-purpose：默认，全能

如果 Skill 里只有规范性内容（"用这些 API 约定"），不要加 context: fork——子 Agent 收到的是规范但没有任务，不知道要干什么，直接返回空的。

几个实际能用的 Skill

代码审查

---
name:review
description:审查当前branch的改动，检查代码质量和潜在问题
disable-model-invocation:true
allowed-tools:
-Bash(git*)
-Read
---

审查当前branch的改动：

1.`gitdiffmain...HEAD`看整体改动
2.重点检查：
   -有没有明显的bug
   -有没有缺少错误处理的地方
   -有没有可以优化的地方
   -命名是否清晰
3.给出具体的改进建议，带上文件名和行号

用法：在准备提 PR 前跑 /review，先自查一遍。

生成单元测试

---
name:gen-test
description:为指定文件生成单元测试
argument-hint:[file-path]
allowed-tools:
-Read
-Write
---

为$ARGUMENTS生成单元测试：

1.读取文件，理解每个函数/方法的功能
2.为每个public方法生成测试用例，覆盖：
   -正常输入
   -边界值
   -异常情况
3.测试文件保存到同目录下，命名规则：原文件名+`.test.ts`
4.使用项目已有的测试框架（从package.json判断）

用法：/gen-test src/utils/date.ts，自动在 src/utils/ 下生成 date.test.ts。

项目架构分析

---
name:arch
description:分析当前项目的架构，生成架构文档
context:fork
agent:Explore
allowed-tools:
-Read
-Glob
-Grep
---

分析当前项目架构：

1.读取package.json了解依赖和脚本
2.扫描主要目录结构
3.找出核心模块和它们之间的依赖关系
4.用Mermaid图表画出依赖关系
5.写一份ARCHITECTURE.md，包含：
   -项目整体架构
   -核心模块说明
   -数据流向
   -关键技术决策

用法：接手一个新项目时跑 /arch，10 分钟出一份架构文档。

踩过的坑

description 写太简单导致不触发

Skill 不触发，八成是 description 写得太笼统。Claude 靠 description 判断相关性，写"帮助用户提交代码"跟写"当用户说 commit、提交、git commit 时触发，根据 staged changes 生成规范的 commit message"，触发准确度差很多。

描述里包含用户会实际说出来的词，比功能描述有用得多。

description 占满了上下文

装太多 Skill 可能会遇到这个：Claude 说"部分 Skill 没有加载"。

Skill 的 description 有字数预算，是 context window 的 2%。装 50 个 Skill 之后，排在后面的会被挤掉。

解决方法：给不常用的 Skill 加 disable-model-invocation: true，这样它的 description 就不会占用预算，需要时手动 / 调用。

或者设置环境变量调大预算：

export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000

context: fork 的 Skill 没有输出

子 Agent 跑完没有返回有用的内容，通常是 SKILL.md 里只有规范没有任务。

错误写法：

---
name:api-style
context:fork
---

API设计规范：
-用RESTful命名
-返回统一的错误格式
-加请求校验

这给子 Agent 的是一份规范，但没说"你要做什么"，它不知道该干什么。

context: fork 适合有明确任务的 Skill，比如"分析这个目录"、"生成这个文档"。纯规范类的 Skill 不要加 context: fork，直接作为参考内容加载就够了。

allowed-tools 限制太死

写了 Bash(git *) 但 Skill 里需要 npm run test，Claude 会说"没有权限执行这个命令"。

检查 Skill 里用到的所有命令，确保 allowed-tools 都配上了。需要多个命令前缀时：

allowed-tools:
  -Bash(git*)
-Bash(npmrun*)
-Bash(npx*)
-Read
-Write

内置 Skill

Claude Code 自带 5 个 Skill，打 / 就能用：

/simplify

写完某个功能后跑一下，它会同时起三个 Agent 并行检查代码复用、质量、执行效率，汇总后逐步改。

/simplify

可以加参数聚焦：

/simplify 重点看内存使用

/batch

大规模改动用这个，比如把整个 src/ 目录从 CommonJS 迁移到 ESM：

/batch 把 src/ 目录下所有文件从 CommonJS 迁移到 ESM

它会分析代码库，拆成 5-30 个独立任务，每个任务在独立的 git worktree 里跑，最后各自提 PR。需要 git 仓库。

/debug

当前 Claude Code session 出问题了，用这个读 debug 日志：

/debug session 越来越慢

/loop

让某个任务定时重复跑，比如每 5 分钟检查一次部署是否完成：

/loop 5m 检查部署状态，看 https://your-app.com/health 返回是否正常

session 关闭后任务也停了。

/claude-api

项目里用到 anthropic 或者 @anthropic-ai/sdk 时自动触发，加载 API 参考文档、tool use、streaming、structured output 等用法。也可以手动 /claude-api 触发。

Skill 本质上就是个 Markdown 文件，照着这篇从头建一个 commit Skill 跑通，就知道整个机制是怎么回事了。

建完之后慢慢加：代码审查、测试生成、文档同步，每个 Skill 试几次迭代一下 description，用着用着就清楚什么时候该用 context: fork、什么时候该加 disable-model-invocation。