用 SKILL.md 打造你的 Claude Code 自定义技能

技能 (Skill) 是一个可复用的指令包（也可以包含脚本），用于扩展 Claude Code 的能力。你只需在一个名为 SKILL.md 的文件里把指令写好一次，Claude 就会把它加入自己的工具箱。

你可以把它看作一份定制的“小抄”。每当任务匹配时，Claude 就能按需加载该技能，并精确遵循你写的指令。这样你就能自动化重复性工作，比如格式化代码、跑一遍发布检查清单、或生成数据库 Schema，而不必每次都重新输入这些步骤。

与把所有内容都塞进 CLAUDE.md 不同，技能的正文只在真正被用到时才加载，所以即使是很长的参考资料，在你需要之前几乎不占用上下文。

每个技能都是一个包含 SKILL.md 文件的文件夹。文件夹放在哪里，决定了谁能使用它：

• 个人级（你的所有项目都可用）：~/.claude/skills/<技能名>/SKILL.md
• 项目级（仅当前仓库，提交后即可共享）：.claude/skills/<技能名>/SKILL.md

文件夹名就是你要输入的命令。位于 .claude/skills/deploy-staging/SKILL.md 的技能，调用方式就是 /deploy-staging。

一个 SKILL.md 由两部分组成：

1. YAML frontmatter，写在 --- 标记之间。最重要的字段是 description——Claude 会读取它来判断何时自动使用该技能。（name 是可选的，只用作显示名称。）
2. Markdown 指令，写在 frontmatter 下方——技能运行时 Claude 需要遵循的步骤。

---
description: 格式化并整理 Markdown 文件。当被要求整理或格式化 .md 文档时使用。
---

格式化 Markdown 文件时：
- 在每个标题前留一个空行
- 删除每行行尾的空格
- 将段落按 80 字符换行

技能文件夹里还可以放配套文件——模板、示例输出，或供 Claude 运行的辅助脚本（Shell 或 Python），但只有 SKILL.md 是必需的。

技能有两种运行方式，理解二者的区别正是技能的精髓所在：

• 由 Claude 自动调用。 Claude 始终能看到每个技能的 description。当你的请求与之匹配时，它会自动加载该技能。你说*“整理一下 README.md”*，一个描述写得好的格式化技能就会自动生效，而无需你点名。
• 由你直接调用，输入 /<技能名>（即文件夹名），例如 /format-md。当你想自己触发技能时就用这种方式。

你可以通过 frontmatter 来控制这一点。加上 disable-model-invocation: true，技能就变成仅限手动触发——这对有副作用的操作很有用，比如 /deploy 或 /commit，你不会希望 Claude 自作主张去运行它们。默认情况下，你和 Claude 都可以调用一个技能。

让我们做一个真正的项目级技能，指导 Claude 如何整理 Markdown 文件。在你的 playground 中创建技能文件夹：

mkdir -p .claude/skills/format-md

现在创建 .claude/skills/format-md/SKILL.md。用编辑器打开它并粘贴：

---
description: 格式化并整理 Markdown 文件。当被要求整理、清理或格式化 .md 文档时使用。
---

格式化 Markdown 文件时：
- 在每个标题前留一个空行
- 删除每行行尾的空格
- 将段落按 80 字符换行

由于这个文件夹叫 format-md，该技能既可以自动使用（根据它的描述），也可以用 /format-md 直接调用。

在 playground 中启动 Claude Code：

claude

先确认 Claude 能看到这个技能。问它：

现在有哪些可用的技能？

你应该能在列表里看到 format-md。接下来分别测试两种调用方式。

直接调用——输入命令并带上目标文件：

/format-md 整理一下 intro.md

自动调用——只描述任务、不点名技能，让 Claude 自己判断：

帮我整理一下 intro.md 的格式

无论哪种方式，Claude 都会读取你技能里的规则，在标题前加上空行、去掉行尾空白、把段落重新换行，并保存结果。

输入 /exit 关闭会话。