Claude Code Skills 教程

更新于 2026-10-21 · 阅读约 20 分钟

Claude Code Skills 是写给 Claude 的"操作手册"：一个 SKILL.md 文件写好某类任务的步骤和要求，Claude 在相关时会自动加载，你也可以输入 /skill名称 直接调用。这篇教程讲 Skill 放在哪里、怎么从零写一个能用的 SKILL.md、怎么控制谁能调用，以及怎么通过插件和插件市场安装别人做好的 Skill。

如果你还没装好 Claude Code，先看 Claude Code 安装教程，再按第三方 API 配置教程接入 cdnd。

Claude Code Skill 是什么

一个 Skill 就是一个目录，里面至少有一个 SKILL.md：开头是 YAML 格式的 frontmatter，告诉 Claude 什么时候用它；后面是 Markdown 正文，是 Claude 执行时要遵循的指令。

什么时候值得写一个 Skill：

你总在对话里重复粘贴同一段要求、同一份检查清单或同一套多步骤流程；
CLAUDE.md 里某一段已经从"事实"长成了"操作流程"。

和 CLAUDE.md 不同，Skill 的正文只在用到时才加载，所以写得再长，平时也几乎不占上下文。

以前放在 .claude/commands/ 里的自定义命令已经并入 Skills：.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会生成 /deploy，用法一样，旧文件继续有效。新写的建议用 Skill 目录，因为它还能带辅助文件、控制调用方式。

Claude Code 的 Skills 遵循 Agent Skills 开放标准，并在此基础上增加了调用控制、子代理执行、动态上下文注入等功能。

Skills 放在哪里

放在哪个目录，决定了哪些会话能用到它：

位置	路径	生效范围
个人	`~/.claude/skills/<名称>/SKILL.md`	你在这台电脑上的所有项目
项目	`.claude/skills/<名称>/SKILL.md`	当前仓库；提交到 git，团队成员也能用
插件	`<插件>/skills/<名称>/SKILL.md`	启用了该插件的地方，命令形式是 `/插件名:名称`
企业	托管设置目录下的 `.claude/skills/<名称>/SKILL.md`	组织统一部署到的所有电脑

几条规则：

monorepo：Claude Code 会从启动目录一直往上找到仓库根目录，加载沿途每一层的 .claude/skills/。启动目录下层子目录里的 Skill，要等 Claude 第一次读写那个子目录里的文件时才加载。
重名：个人 Skill 优先于项目 Skill；Skill 优先于 .claude/commands/ 里的同名文件；你自己的 Skill 会替换同名的内置 Skill（别名除外）。插件 Skill 带插件名前缀，不会和它们冲突。
改了立即生效：Claude Code 会监视 Skill 目录，新增、修改、删除 Skill 不用重启会话。如果是会话启动后才新建的顶层 skills 目录，运行 /reload-skills 让它被发现。
删除：直接删掉 Skill 所在的目录即可。

编写你的第一个 SKILL.md

下面做一个 summarize-changes Skill：总结 git 仓库里还没提交的改动，并指出有风险的地方。它会先把真实的 diff 塞进提示里，所以 Claude 依据的是你工作区的实际改动，而不是猜测。

第一步：创建目录

放在个人目录下，所有项目都能用：

Terminal

mkdir -p ~/.claude/skills/summarize-changes

Windows PowerShell：

PowerShell

New-Item -ItemType Directory -Force "$HOME\.claude\skills\summarize-changes"

第二步：写 SKILL.md

把下面的内容保存为 ~/.claude/skills/summarize-changes/SKILL.md：

Markdown

---
description: 总结未提交的改动并指出风险。当用户问改了什么、想要提交说明、或者让你审查 diff 时使用。
---

## 当前改动

!`git diff HEAD`

## 要求

用两到三条要点总结上面的改动，然后列出你注意到的风险，比如缺少错误处理、写死的值、需要更新的测试。如果 diff 为空，就说明没有未提交的改动。

几个要点：

命令名：目录名就是你要输入的命令，这里是 /summarize-changes。也可以在 frontmatter 里用 name 另起一个。
description：Claude 靠它判断什么时候自动加载这个 Skill，把最主要的使用场景写在前面，写上用户自然会说的词。
!`git diff HEAD`：这是动态上下文注入。Claude Code 会先运行这条命令，用输出替换这一行，Claude 拿到的就是当前的 diff。
frontmatter 的开头 --- 必须是文件第一行，否则整个文件都会被当成正文。
Windows 上没有安装 Git Bash 时，在 frontmatter 里加一行 shell: powershell，让 ! 命令用 PowerShell 运行。

第三步：测试

打开一个 git 项目，随便改一个文件，运行 claude。可以让 Claude 自动调用，问一句和 description 相符的话：

Claude Code

我改了什么？

也可以直接调用：

Claude Code

/summarize-changes

两种方式都应该得到一段改动总结和风险列表。

常用 frontmatter 字段

所有字段都是可选的，只有 description 建议必填。字段名写错不会报错，只会被忽略，所以要和下表完全一致：

字段	作用
`name`	`/` 菜单里显示的命令名，默认是目录名
`description`	Skill 做什么、什么时候用；和 `when_to_use` 合计超过 1,536 个字符会被截断
`when_to_use`	补充触发场景，比如示例请求
`argument-hint`	自动补全时提示要传什么参数，如 `[issue-number]`
`disable-model-invocation`	设为 `true` 后 Claude 不会自己调用，只能你手动 `/名称`
`user-invocable`	设为 `false` 后只有 Claude 能调用，`/` 菜单里不显示
`allowed-tools`	调用这个 Skill 的那一轮里，列出的工具不用再确认
`model`	这个 Skill 生效期间使用的模型，只影响当前这一轮
`context`	设为 `fork` 时在独立的子代理里运行
`paths`	文件匹配这些 glob 时才自动加载

带参数和辅助文件

正文里的 $ARGUMENTS 会被替换成命令后面的内容，$0、$1 按位置取单个参数：

Markdown

---
name: fix-issue
description: 修复一个 GitHub issue
disable-model-invocation: true
---

按照我们的编码规范修复 GitHub issue $ARGUMENTS：

1. 阅读 issue 描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建提交

运行 /fix-issue 123，Claude 收到的就是"按照我们的编码规范修复 GitHub issue 123……"。

Skill 目录里还可以放参考文档、示例和脚本，在 SKILL.md 里写明每个文件是什么、什么时候读，Claude 需要时才会加载。官方建议 SKILL.md 控制在 500 行以内，详细资料拆到单独的文件里。引用 Skill 自带的脚本时用 ${CLAUDE_SKILL_DIR}，它会被替换成 SKILL.md 所在的目录：

Text

my-skill/
├── SKILL.md       （必需：概述和导航）
├── reference.md   （详细文档，需要时加载）
├── examples.md    （示例，需要时加载）
└── scripts/
    └── helper.py  （脚本，执行而不是加载）

调用 Skills

自动调用：Claude 看到你的请求和某个 Skill 的 description 相符时，会自己加载它。
手动调用：在消息开头输入 /名称，后面可以跟参数，例如 /fix-issue 123。
写在句子中间：先跑测试，然后 /deploy 到 staging 这种写法不会直接运行，只表示你允许 Claude 在这次回复里调用它，由 Claude 根据你的意思判断。只想提到这个 Skill 而不授权运行，就别加斜杠。
一次叠加多个：在终端里可以在一条消息开头连写几个 Skill，比如 /write-tests /fix-issue 123，两个都会加载，123 作为参数传给每一个，最多叠加六个。

输入 /skills 查看所有可用的 Skill：输入文字筛选，按 t 按 token 数排序，按 Space 或 Enter 切换某个 Skill 的可见性，按 Esc 保存到 .claude/settings.local.json。在 VS Code 插件里同样可以输入 /skills，见 Claude Code VS Code 插件教程。

Skill 也占上下文

默认情况下，每个 Skill 的名称和描述每一轮都在上下文里，这样 Claude 才知道有哪些可用；正文在调用时加载，之后一直留在对话里。所以正文要写得精简，不常用的 Skill 可以关掉。上下文按 token 计费，价格见 Claude Code 价格。

内置 Skills

Claude Code 自带一批内置 Skill，用法和你自己写的一样，输入 / 加名称调用。它们是基于提示词的：给 Claude 一套详细指令，由它调用工具完成；而大多数内置命令是直接执行固定逻辑。

Skill	作用
`/doctor`	检查安装、设置、扩展和 CLAUDE.md 的问题，确认后再修复（别名 `/checkup`）
`/code-review`	审查当前改动、某个 PR、分支或路径里的正确性问题
`/simplify`	检查改动的代码能否简化并直接修改（不找 bug）
`/debug`	打开调试日志并读取日志排查问题
`/batch`	把大规模改动拆成多个独立单元并行完成
`/loop`	会话打开期间重复执行一个提示
`/run`、`/verify`	启动应用、确认改动在运行中的应用里真的生效
`/run-skill-generator`	为项目生成一个 Skill，记录怎么构建和启动你的应用
`/claude-api`	加载 Claude API 的参考资料，代码里引用 Anthropic SDK 时会自动启用

有的内置 Skill 由 Claude 在相关时自动调用，有的（比如 /verify）只在你手动调用时运行。想全部关掉，用 disableBundledSkills 设置。全部命令见 Claude Code 命令大全。

控制谁能调用 Skill

默认情况下，你和 Claude 都能调用任何 Skill。两个 frontmatter 字段可以收紧：

frontmatter	你能调用	Claude 能调用	什么时候进入上下文
（默认）	能	能	描述一直在上下文里，调用时加载全文
`disable-model-invocation: true`	能	不会自己调用	描述不在上下文里，调用时加载全文
`user-invocable: false`	不能	能	描述一直在上下文里，调用时加载全文

有副作用的流程，比如部署、提交、发消息，加 disable-model-invocation: true，你不会希望 Claude 觉得"代码看起来好了"就自己去部署。
纯背景知识，比如某个老系统的工作原理，加 user-invocable: false，Claude 需要时会参考，但它不适合作为一条命令给人调用。

不想改 SKILL.md（比如团队仓库里的 Skill）时，可以在设置里用 skillOverrides 控制可见性，取值 on、name-only、user-invocable-only、off；/skills 菜单里切换可见性写的就是它。插件里的 Skill 不受 skillOverrides 影响，要在 /plugin 里管理。

通过插件和插件市场分享 Skills

插件是把 Skills、子代理、hooks、MCP 服务器打包在一起的目录，通常带一个 .claude-plugin/plugin.json 清单。插件市场则是一个插件目录：通常是一个 GitHub 仓库，用 .claude-plugin/marketplace.json 列出插件和获取地址。

从 Claude Code 插件市场安装

第一次启动交互式终端会话时，Claude Code 会自动添加 Anthropic 官方市场 claude-plugins-official。在会话里输入：

Claude Code

/plugin

打开插件面板，在 Discover 标签页搜索浏览。知道名字的话可以直接打开详情：

Claude Code

/plugin install commit-commands@claude-plugins-official

这条命令不会立刻安装，而是先显示插件会添加哪些命令、Skill、hooks 和 MCP 服务器（官方市场的插件还会显示上下文开销估算），然后让你选择安装范围：

范围	生效范围
用户（user）	你在这台电脑上的所有项目
项目（project）	这个仓库的所有协作者，写进提交到 git 的 `.claude/settings.json`
本地（local）	只对你、只在这个仓库

装好后输入 / 就能看到插件提供的 Skill，形式是 /插件名:skill名，例如 /commit-commands:commit。在终端外也可以用 claude plugin install <插件>@<市场> 安装，用 claude plugin list 查看已装插件。VS Code 插件里输入 /plugins 打开图形界面管理，和命令行共用同一份配置。

添加其他插件市场

Claude Code

/plugin marketplace add anthropics/claude-plugins-community

Anthropic 社区市场：仓库 anthropics/claude-plugins-community，安装时后缀写 @claude-community。
Anthropic 专题市场：例如 anthropics/skills。
第三方市场：/plugin marketplace add <owner>/<repo> 添加，再用 /plugin install <插件>@<市场名> 安装，市场名在添加成功后会打印出来。

项目内共享：把 .claude/skills/ 提交到 git，拉代码的人都能用。
跨项目、跨团队分发：在插件里建一个 skills/ 目录放 Skill，再发布到你自己的插件市场。
整个组织：通过托管设置统一部署。

Skills、CLAUDE.md 和斜杠命令怎么选

	CLAUDE.md	Skill	自定义斜杠命令（`.claude/commands/`）
加载时机	每次对话开始自动加载	描述常驻，正文用到时才加载	和 Skill 相同（已并入 Skills）
适合放	每次都要知道的事实：构建命令、代码规范、目录说明	某类任务的流程、检查清单、长篇参考资料	旧项目里已有的命令，继续可用
调用方式	无需调用	Claude 自动调用或 `/名称`	`/文件名`

经验法则：每次都要遵守的事实写进 CLAUDE.md；只在特定任务里用到的流程写成 Skill；必须每次都执行、不能靠 Claude 自觉的规则（比如每次改文件后跑格式化），用 hooks。CLAUDE.md 的用法见 Claude Code 使用教程。

Skill 不生效怎么排查

Skill 没有被自动调用

检查 description 里有没有你提问时自然会用的词。
问 Claude "现在有哪些可用的 Skill？"，确认它在列表里。
换个和 description 更接近的说法再试，或者直接 /名称 调用。
frontmatter 的 YAML 写错时，Skill 仍会加载但没有任何字段，/名称 能用、自动调用失效。用 claude --debug 启动可以看到解析错误，或者运行 claude plugin validate ~/.claude/skills 检查。

Skill 被调用得太频繁

把 description 写得更具体；如果只想手动调用，加上 disable-model-invocation: true。

对话后半段 Claude 不再遵循 Skill

Skill 的内容在调用时加入对话，之后不会重新读取文件。上下文压缩后，每个 Skill 只保留开头的一部分（最多 5,000 个 token），所以最重要的要求要写在 SKILL.md 前面；需要时再调用一次即可恢复完整内容。

常见问题

Claude Code Skills 和 MCP 有什么区别？

Skill 是写给 Claude 的指令和流程，本质是一份 Markdown 文档，告诉 Claude 怎么做一件事。MCP 是把数据库、浏览器、设计工具等外部工具接进 Claude Code，给 Claude 新的能力。两者可以配合：Skill 里写清楚什么时候、怎么用某个 MCP 工具。

SKILL.md 必须写 frontmatter 吗？

不是必须的，所有字段都可选。没有 description 时，Claude Code 用正文第一行非空内容作为描述。但为了让 Claude 在合适的时候自动调用，建议至少写上 description。

个人 Skill 和项目 Skill 重名了，用哪个？

个人 Skill（~/.claude/skills/）优先于项目 Skill（.claude/skills/）。插件里的 Skill 带插件名前缀，比如 /my-plugin:review，不会和它们冲突。

以前写的 .claude/commands 自定义命令还能用吗？

能。自定义命令已经并入 Skills，.claude/commands/ 里的文件继续有效，和同名 Skill 用法一样。如果同名的 Skill 和命令文件同时存在，以 Skill 为准。新写的建议用 Skill 目录，可以带辅助文件和调用控制。

用 cdnd 时能用 Skills 和插件市场吗？

能。Skill 和插件都装在你本地，接入 cdnd 后照常使用，模型是官方 Claude，不掺假、不降智。唯一不同的是不会同步 claude.ai 账号里的 Skills，需要的 Skill 放进 ~/.claude/skills/ 或项目的 .claude/skills/ 即可。

Skills 会增加花费吗？

会有一些。每个可自动调用的 Skill，名称和描述每一轮都在上下文里；调用后正文留在对话中。上下文都按 token 计费，所以 Skill 正文要精简，不用的 Skill 和插件可以关掉。cdnd 按 Anthropic 官方标价计费，充值 ¥2 = $1。

VS Code 插件里能用 Skills 吗？

能。VS Code 插件支持部分斜杠命令和 Skills，输入 / 查看可用的，输入 /skills 可以查看和切换 Skill 的可见性。需要全部命令时，在 VS Code 的集成终端里运行命令行版 claude。

Claude Code Skills 教程

Claude Code Skill 是什么

Skills 放在哪里

编写你的第一个 SKILL.md

第一步：创建目录

第二步：写 SKILL.md

第三步：测试

常用 frontmatter 字段

带参数和辅助文件

调用 Skills

Skill 也占上下文

内置 Skills

控制谁能调用 Skill

通过插件和插件市场分享 Skills

从 Claude Code 插件市场安装

添加其他插件市场

分享你自己的 Skill

Skills、CLAUDE.md 和斜杠命令怎么选

Skill 不生效怎么排查

Skill 没有被自动调用

Skill 被调用得太频繁

对话后半段 Claude 不再遵循 Skill

常见问题

Claude Code Skills 和 MCP 有什么区别？

SKILL.md 必须写 frontmatter 吗？

个人 Skill 和项目 Skill 重名了，用哪个？

以前写的 .claude/commands 自定义命令还能用吗？

用 cdnd 时能用 Skills 和插件市场吗？

Skills 会增加花费吗？

VS Code 插件里能用 Skills 吗？

现在开始