用法

Claude Code Skills 使用教程：SKILL.md 怎么写、放哪里、怎么触发

发布于 2026 年 10 月 30 日 · 最后核对 2026 年 10 月 30 日

skill 是一个带说明的 SKILL.md 文件：Claude 觉得相关时会自己用它，你也可以用 /skill-name 直接调用。这一页按 Anthropic 的 Extend Claude with skills 文档，中文整理怎么创建第一个 skill、skill 放在哪里、frontmatter 怎么写、怎么控制谁来调用，以及不触发时怎么排查。文档于 2026 年 10 月 30 日核对。

什么时候该写 skill

文档给的判断标准：你一直在往对话里粘贴同样的说明、清单或多步流程，或者 CLAUDE.md 里有一段已经从“事实”变成了“流程”，就适合写成 skill。和 CLAUDE.md 的内容不同，skill 的正文只在被用到时才加载，所以很长的参考资料在用到之前几乎不占上下文。CLAUDE.md 的写法见 CLAUDE.md 怎么写。

文档还说明，自定义命令已经合并进 skill：.claude/commands/deploy.md 处的文件和 .claude/skills/deploy/SKILL.md 处的 skill 都会创建 /deploy，工作方式相同，已有的 .claude/commands/ 文件继续可用。skill 多出来的是：存放辅助文件的目录、控制由你还是 Claude 调用的 frontmatter，以及让 Claude 在相关时自动加载的能力。

创建第一个 skill

下面这个例子来自文档：总结 git 仓库里未提交的改动，并标出有风险的地方。第一步，在个人 skills 目录里建一个文件夹，个人 skill 在你所有的项目里都可用：

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

第二步，写 SKILL.md。每个 skill 都需要这个文件，由两部分组成：--- 标记之间的 YAML frontmatter，告诉 Claude 什么时候用这个 skill；后面的 markdown 正文，是 skill 运行时 Claude 要遵循的说明。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

目录名（设置了 frontmatter name 时用 name）就是你输入的命令，description 帮助 Claude 判断什么时候自动加载。!`git diff HEAD` 这一行是文档说的动态上下文注入：Claude Code 先运行这条命令，用输出替换这一行，Claude 看到的 skill 内容里已经带着当前的 diff。

第三步，测试。打开一个 git 项目，随便改一个文件，运行 claude，两种方式都可以：

What did I change?     # 问一句和 description 匹配的话，让 Claude 自动调用
/summarize-changes     # 或者用 skill 名直接调用

两种方式下，Claude 都应该给出对改动的简短总结和风险列表。

skill 放在哪里

保存的位置决定哪些会话会加载它：放在 home 目录下，所有项目都有；提交到仓库，在这个仓库里工作的人都有；也可以通过 plugin 或托管设置分发给整个团队。

重名时的规则（文档原表的节选）：

• 企业、个人、项目里有两个同名：企业优先于个人，个人优先于项目。~/.claude/skills/ 和项目的 .claude/skills/ 里都有 deploy 时，/deploy 运行个人的那个。
• skill 和 .claude/commands/ 里的文件同名：skill 优先。
• plugin skill 和上面任一位置的 skill 同名：两个都会加载，因为 plugin skill 的命名空间是 /plugin-name:skill-name。

另外，.claude/skills/ 在你启动目录的下层子目录里时，启动时不会加载，要等 Claude 第一次读取或编辑那个子目录里的文件才会加载；在那之前，它们不出现在 / 菜单里，也不能按名字调用。

改动 skill 不需要重启。Claude Code 会监视 skill 目录，在 ~/.claude/skills/、项目的 .claude/skills/ 下新增、编辑或删除 skill，当前会话内就会生效。如果你创建的是会话启动时还不存在的顶层 skills 目录，运行 /reload-skills。

最常用的 frontmatter 字段

所有字段都是可选的，只有 description 是推荐的。字段名必须和表里完全一致，连字符也一样：Claude Code 会忽略不认识的字段，而且不报错。布尔字段除了 true 和 false，还接受 yes、no、on、off、1 和 0（字母大小写均可）。

文档里还有 model、effort、agent、background、hooks、shell、metadata、license、compatibility 等字段，这里不展开。有一条要注意：Claude Code 只在开头的 --- 是文件第一行时才读 frontmatter，否则把整个文件（包括 ---）当作 skill 内容。

自己调用，还是让 Claude 决定

默认情况下，你和 Claude 都可以调用任何 skill：你输入 /skill-name 直接调用，Claude 觉得和对话相关时自动加载。两个 frontmatter 字段可以限制：

• disable-model-invocation: true：Claude 不能自己调用。用于有副作用、或者你想自己控制时机的流程，比如 /commit、/deploy、/send-slack-message，你不希望 Claude 因为代码看起来好了就决定去部署。
• user-invocable: false：只有 Claude 能调用。用于不适合当命令用的背景知识，比如解释旧系统怎么运作的 legacy-system-context。

文档的 deploy 示例：

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

如果 Claude 仍然想用，Claude Code 会拦下这次调用，并告诉它不要用别的方式重现部署步骤，所以预期 Claude 会建议你自己运行 /deploy。

要直接运行 skill，把名字放在消息开头：/deploy staging 由 Claude Code 直接运行。如果名字出现在普通文字之后，例如 go ahead and /deploy to staging，不会直接运行；这个名字算作你对这条消息的许可，Claude 回复时可以运行这个 skill，并根据你的措辞判断你是不是要它运行。只想谈论这个 skill 而不允许运行，就去掉斜杠。

传参数和辅助文件

你和 Claude 调用 skill 时都可以传参数，参数通过 $ARGUMENTS 占位符取用，它会被替换成 skill 名后面的内容：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

运行 /fix-issue 123 时，Claude 收到的是 “Fix GitHub issue 123 following our coding standards...”。想按位置取单个参数，用 $ARGUMENTS[N] 或更短的 $N。如果调用时带了参数，但内容里没有任何占位符接收它，Claude Code 会在 skill 内容末尾追加 ARGUMENTS: <your input>，让 Claude 仍然看到你输入的内容。

skill 目录里可以放多个文件。这样 SKILL.md 只写要点，详细的参考资料让 Claude 需要时再读：

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

要在 SKILL.md 里引用这些文件，让 Claude 知道每个文件里有什么、什么时候该加载：

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

文档的提示：SKILL.md 保持在 500 行以内，把详细的参考材料移到单独的文件里。

怎么写好 description

• 写用户自然会说的关键词。文档的排查第一条就是检查 description 里有没有用户会自然说出的词。上面的例子把“什么时候用”直接写进去：“Use when the user asks what changed, wants a commit message, or asks to review their diff.”
• 把最主要的用途放在最前面。description 和 when_to_use 合起来在 skill 列表里最多保留 1,536 个字符，超出的部分会被截断。
• 如果描述太宽，就写具体。skill 触发得太频繁时，文档的第一条建议是让 description 更具体。
• 尖括号会被转义。description 和 when_to_use 里的 < 和 > 会显示成 < 和 >。要显示 <branch> 这样的占位符，改用方括号 [branch]，或者把它挪到单独的 argument-hint 行。
• 正文要简短。skill 一旦加载，内容会在后续轮次一直留在上下文里，每一行都是持续的 token 成本；写“做什么”，而不是叙述“怎么做”或“为什么”。

常见问题排查

skill 没有触发

• 检查 description 里有没有用户会自然说出的关键词。
• 确认 skill 出现在 What skills are available? 的回答里。
• 换个说法，让请求更贴近 description。
• 如果 skill 允许用户调用，直接用 /skill-name 调用。
• 如果 /skill-name 也不被识别，检查 Claude Code 是不是拒绝了这个 skill 的名字（零宽空格、控制字符、< 或 > 等字符会导致被拒）。
• 如果 skill 设置了 paths，检查 Claude 读取、编辑或写入的文件是否在当前工作目录之内；在目录之外的文件（例如同级 git worktree 里的文件，即使用 /add-dir 加进来）不会激活这个 skill。

如果 frontmatter 的 YAML 格式有误，Claude Code 会以空元数据加载 skill 正文：/skill-name 仍然能用，但 Claude 没法按 description 匹配。用 --debug 运行可以看到解析错误。查找 frontmatter 解析失败的 SKILL.md，可以对 skills 目录运行 claude plugin validate，例如 claude plugin validate .claude/skills 或 claude plugin validate ~/.claude/skills（需要 Claude Code v2.1.233 或更高版本）。

skill 触发太频繁

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

Claude 中途不再遵循 skill

skill 被调用时，Claude Code 把它的内容加进对话，之后的轮次不会重新读取文件，所以对整个任务都适用的指引，要写成“每次编辑后运行测试”，而不是“运行测试”。对话被压缩后，Claude Code 只能保留已调用 skill 的开头，所以把最重要的说明放在 SKILL.md 靠前的位置，必要时重新调用一次 skill 来恢复完整内容。必须每次都成立的规则，文档建议移到 hook 里。

description 被截断

skill 很多时，Claude Code 会为了符合列表的字符预算而丢掉一部分 description，Claude 匹配请求需要的关键词也就没了；预算是模型上下文窗口的 1%，从你最少调用的 skill 开始丢。运行 /doctor 可以估算列表占用的上下文，并看到占用最多的项。

常见问题

来源

• Claude Code：Extend Claude with skills（skill 位置、重名规则、frontmatter 字段、调用控制、参数、辅助文件、排查）