Claude Code Skills 从零创建 SKILL.md 教程
Skill 是 Claude Code 的一种”可复用专长包”：你把一段专门的知识或固定流程写进一个 SKILL.md 文件，Claude 在判断当前任务相关时自动加载它，从而按你预设的方式干活。 简单说，它就是给 AI 助手挂载的”专业手册”——平时不占上下文，需要时才翻开。
这篇带你从零写出第一个能跑的 Skill：理解它的加载机制、写对 SKILL.md 的 frontmatter、目录怎么放、以及它和 subagent（规划中）、command 的边界。本文针对 Claude Code 用户，但思路对任何支持类似机制的工具都通用。
Skill 到底解决什么问题
没有 Skill 时，你只能靠两种笨办法让 Claude”懂行”：要么每次对话手动粘贴一大段说明，要么把所有规则塞进 CLAUDE.md 常驻上下文。前者累、后者把上下文撑爆。
Skill 的核心价值是”按需加载”：
- 省 token——只有任务相关时才把完整内容读进来。
- 可复用——写一次，所有项目/对话复用，不用反复复制粘贴。
- 可沉淀团队经验——把”我们公司怎么写 commit""怎么调这套 API”固化成文件，新人和 AI 都照着做。
一句话：Skill = 把你脑子里的专门流程，变成 Claude 随用随取的标准操作手册。
举个我自己踩过的场景：团队里 commit message 要求写成 <类型>(<范围>): <主题> 且中文描述，之前每次都得在对话里现补一句”记得按我们的格式写”，AI 有时候记得有时候不记得，全看当轮上下文挤不挤得下。写成一个 commit-helper Skill 之后，我只要照常说”帮我提交一下”，Claude 自己判断该加载这条规则、自己去读 git diff --staged、自己按格式起标题——省的不是一两句话，是”我得不得记得每次都提醒它”这件事本身。这才是 Skill 真正省的地方：不是省字数，是省你脑子里那根一直绷着的弦。
渐进式加载：Skill 怎么被”想起来”
这是 Skill 最该理解的机制，也是它长青的地方——机制不变，具体字段以官方文档为准。
Claude Code 对 Skill 采用渐进式（progressive）加载，分三层，逐层才读更多：
- 第一层只读元数据——启动时，Claude 只扫描每个 Skill 的
name和description，几乎不耗上下文。这就像只看书的标题和简介。 - 第二层读正文——当你的请求与某个
description匹配时，Claude 才把整个SKILL.md正文读进来，按里面的指引干活。 - 第三层读附带资源——
SKILL.md里若引用了额外脚本、模板或参考文档，Claude 在确实需要时才进一步打开它们。
触发机制的关键全压在 description 上。 Claude 靠它判断”这个任务该不该用这个 Skill”。所以 description 必须写清楚：这个 Skill 是干嘛的 + 什么时候该用它。写得含糊，Skill 就永远”想不起来”。
对比一下两种写法就知道差距在哪：
- 含糊版：
description: 处理 PDF 相关任务。——Claude 看到”帮我把这份合同转成 PDF”和”提取这份 PDF 里的表格”时，很可能压根不会想到有这个 Skill，因为它没法从这句话里判断”提取表格”算不算”PDF 相关任务”。 - 具体版：
description: 提取、生成、合并、拆分 PDF 文档，处理 PDF 表单填写。当用户要从 PDF 里取数据、把内容导出成 PDF、合并多个 PDF、或填写 PDF 表单时使用。——这一句里塞满了动词（提取/生成/合并/拆分/填写）和场景（导出成 PDF、合并多个、填写表单），命中率明显更高。
写 description 时给自己定个门槛：如果你自己拿这句话去猜”什么请求会命中”，猜不出至少三种真实场景，这句 description 就还不够具体。
第一步：建好目录结构
Skill 是一个文件夹，里面至少有一个 SKILL.md。最小结构如下：
my-skill/
└── SKILL.md
需要附带资源时，把脚本、模板放进同目录，在正文里引用：
pdf-report/
├── SKILL.md
├── template.md
└── scripts/
└── build.py
放置位置分两种（具体路径以官方文档为准）：
- 个人级——放在用户主目录下的 Claude 配置目录里，所有项目都能用。
- 项目级——放在项目仓库内，随仓库提交，团队共享。
判断口诀：只对你自己有用的放个人级；要团队照着干的放项目级、进 Git。
第二步：写对 SKILL.md 的 frontmatter
SKILL.md 顶部是一段 YAML frontmatter，最关键的就两个字段：
---
name: commit-helper
description: 按本仓库规范生成 git commit message。当用户要提交代码、写 commit、或问"这个改动怎么提交"时使用。
---
# 提交信息助手
## 流程
1. 先看 `git diff --staged` 的实际改动
2. 按 <类型>(<范围>): <主题> 格式起一行标题
3. ……
写好这两个字段的要点：
- name——简短、用小写连字符（kebab-case），见名知意。
- description——第三人称、说清”做什么 + 何时触发”。这是触发的命门，宁可写满信息也别偷懒。把用户可能的真实说法（“帮我提交""写个 commit”）写进去，命中率更高。
注意：frontmatter 的键分隔冒号要用半角
:，全角冒号会让 YAML 解析失败。这条对写 Skill 和写本站文章一样是铁律。
第三步：正文写”流程”还是”知识”
SKILL.md 的正文（frontmatter 之下的 Markdown）就是 Claude 真正照着执行的内容。两类内容最适合放进来：
- 专门流程——固定的多步操作。如”发版流程""怎么跑这套测试""数据库迁移步骤”。用有序步骤写，越具体越好，能给可复制命令就给。
- 专门知识——某个领域/某套内部 API/某种文档风格的规则。如”我们的品牌文案口吻""这套 SDK 的调用约定”。
写作建议：
- 正文别太长。核心步骤留在
SKILL.md，大段参考资料拆到附带文件，靠第三层加载——这样既清晰又省上下文。 - 写成”给 AI 的操作手册”，不是写给人读的散文。多用清单、步骤、代码块。
- 可被验证。流程里带上”怎么确认这步成功了”，Claude 会照着自检。
Skill / subagent / command 怎么区分
新手最容易混这三个。一句话各自定位：
| 机制 | 是什么 | 何时用 |
|---|---|---|
| Skill | 一包专门知识/流程，Claude 按需自动加载 | 想让 AI”会某件事”，且希望它自己判断何时用 |
| subagent | 一个独立的子代理，带自己的上下文窗口去跑子任务 | 想把一大块活外包出去并行/隔离处理 |
| command | 你手动触发的快捷指令（斜杠命令） | 想用一个短命令显式发起某个固定动作 |
判断口诀：
- 要”自动想起来用” → Skill（靠 description 触发）。
- 要”开一个干净上下文跑子任务” → subagent，详见 Claude Code 子代理用法（规划中）。
- 要”我打个命令它就执行” → command（人为触发，不靠 AI 判断）。
三者不冲突，常组合用：用一个 command 显式启动流程，流程里调起 subagent，subagent 又加载相关 Skill。具体能力边界与配置语法以官方文档为准。
新手常见坑
- description 太笼统 → Skill 永远不触发。 这是头号坑。把”何时用”和用户真实说法写进去。
- 把所有东西都堆进 SKILL.md → 上下文浪费。 拆附带文件，利用渐进式加载。
- frontmatter 用了全角冒号 → 加载失败。 一律半角
:。 - 该放项目级却放了个人级 → 团队同事用不上。 要共享就进 Git。
- 正文写得像文章不像手册 → AI 执行走样。 用步骤和清单，别写大段叙述。
- 写完从来没实测过 → 上线才发现根本不触发。 至少拿三句你猜测用户会说的真实话去试一遍，命中了再收工。
常见问题
Skill 和 CLAUDE.md 有什么区别？
CLAUDE.md 是常驻上下文，每次对话都加载，适合放全局少量规则；Skill 是按需加载，平时不占上下文，适合放体量较大、只在特定任务用的专门流程。规则多了，就从 CLAUDE.md 挪进 Skill。
怎么知道我的 Skill 有没有被触发？
最直接的办法是发一个明显该命中的请求，观察 Claude 的行为是否按 SKILL.md 里的流程走。没触发，八成是 description 写得不够清楚——补上”何时使用”和真实问法再试。
一个 Skill 能引用别的文件吗？
能。在 SKILL.md 正文里引用同目录下的脚本、模板或参考文档，Claude 会在确实需要时（第三层加载）才打开它们。这正是控制上下文体积的推荐做法。
写 Skill 需要会编程吗？
不需要。SKILL.md 本质是 Markdown 加一小段 YAML，会写文档就能写。只有当你想让 Skill 调用脚本时，才涉及一点代码。完全不会编程也能用 AI 写代码，写 Skill 同理。
👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。