我今天本来没打算深挖这个。我只是想搞明白，为什么同事的 Claude Code 配置和我的差这么多——结果答案就躺在一个我几乎没注意过的文件夹里。
Claude Code Skills Documentation 涵盖什么
开发者搜索里经常会出现 "anthropic claude code skills documentation" 这个词组，我觉得这不是没有原因：skills 这套系统确实散落在几个不同的界面和文档面上，想把它们之间怎么连起来拼清楚，往往要花一点时间。
这篇文章基于 Anthropic 的官方资料。但我想补上的，是那些单靠文档本身还不太够的东西——一种更慢一点的理解层，是从观察里一点点长出来的。
在哪里看官方文档
最权威的起点，是 Anthropic's Claude Code skills reference，里面覆盖了完整的 skill 生命周期、SKILL.md 格式，以及 Claude 如何自动发现并加载 skills。
如果你想理解 skills 放进更大的 agent 图景里是什么位置——包括它和 Projects、MCP、subagents 之间怎么比较——Anthropic 还发过一篇很有用的博客：Skills explained: How Skills compares to prompts, Projects, MCP, and subagents。那篇文章帮我弄明白的，不只是 what，还有 when。
这篇文章比官方文档多补了什么
官方文档是准确的，结构也很好。它不总能抓住的，是那些细小的意外模式——比如某个 skill 没触发，或者触发得太宽，或者你突然意识到，自己一直把 SKILL.md 和 CLAUDE.md 当成差不多的东西，可它们其实在做两份略微不同的工作。
我想在这里追的，就是这些。
SKILL.md 格式参考
文件位置与命名
每个 skill 都需要一个 SKILL.md 文件，里面分成两部分：YAML frontmatter（位于 --- 标记之间），告诉 Claude 什么时候该用这个 skill；以及 markdown 正文，写 Claude 在 skill 被调用时要遵循的指令。
在 Claude Code 里，skills 可以放在 Project 内的 .claude/skills/<skill-name>/SKILL.md，也可以放在用户全局的 ~/.claude/skills/<skill-name>/SKILL.md。文件夹名和 frontmatter 里的 name 字段会变成斜杠命令，所以如果 .claude/skills/explain-code/SKILL.md 里写的是 name: explain-code，就会创建 /explain-code 这个命令。
定义在 .claude/skills/ 下、并通过 --add-dir 加入的 skills 会被自动加载，而且实时变更检测也能跟上，所以你甚至可以在会话过程中直接改它们，不用重启。这点让我有点意外——我原本以为得重开一次。
支持哪些指令类型
Skills 通过指令和代码，给 Claude 补上一些新能力。实际里，markdown 正文几乎可以放任何 Claude 能推理的东西：分步流程、风格规则、输出模板、领域术语、参考内容，以及内联示例。写指令时，最好用祈使句。
官方 skill-creator 文档里有个细节我觉得值得记一下：description 字段才是最主要的触发机制——既要写清这个 skill 做什么，也要写清它在什么场景下该用。所有“什么时候该用”的信息，都应该放这里，而不是正文里。
格式语法与结构
最小可用的 SKILL.md 长这样：
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude follows when this skill is active]
启动时，agent 会把每个已安装 skill 的 name 和 description 预加载进 system prompt。这个元数据是渐进式披露的第一层：它先给 Claude 一点刚刚好的信息，让它知道什么时候该用哪个 skill，而不是把全部内容一口气塞进上下文。
Skills 也可以带 supporting files——参考文档、脚本、素材——放在子目录里。把表单填写说明之类的内容拆到单独文件后，skill 作者就能让核心 skill 保持很轻，假设 Claude 只会在真的需要时再去读那个文件。
字符与长度限制
SKILL.md 本身没有硬性的字符上限。一个 skill 能打包进去的上下文，理论上几乎没有边界，因为渐进式披露意味着 Claude 只会在需要的时候加载额外文件。但在实际里，如果把 SKILL.md 聚焦在核心指令上——控制在 500 行以内——上下文膨胀会小很多。更细的内容，最好搬到 references/ 里，再从正文链接过去。
Claude Code Skills 能指挥什么
风格与格式偏好
Skills 很适合编码输出标准：报告该怎么组织、语气用什么样、要带哪些标题。你完全可以做一个品牌规范 skill，把公司的配色、字体规则、版式要求都放进去。这样 Claude 在生成演示文稿或文档时，就会自动套用这些标准，不用你每次再解释一遍。
领域专用知识
这大概是 skills 在日常工作里最有用的地方。凡是 Claude 靠通用训练不可能知道、但又必须知道的领域信息——比如你们内部的 API 约定、专有数据格式、公司独有的工作流——都可以打包进一个 skill 里，以后反复复用，不用每个 prompt 都重说。
工具使用偏好
Skills 还能指定 Claude 更该优先用哪些工具、按什么顺序用、在什么条件下用。当 Claude 调用一个 skill 时，系统会走一条相当简单的流程：先加载 SKILL.md，再把它展开成更细的指令，把这些指令作为新的 user message 注入对话上下文，修改执行上下文（可用工具、模型选择），然后在这个被增强过的环境里继续对话。
输出结构要求
你也可以在 skill 里定义非常精确的输出模板。Anthropic skills GitHub repository 里有好几个例子，展示了怎么把 Claude 锚定到明确的格式上——报告结构、commit message 模式、测试文件布局。
Skills 做不到什么
执行代码
SKILL.md 是指令内容，不是可执行代码。它告诉 Claude 怎么 处理一个任务；它自己不会运行任何东西。放在 skill 的 /scripts 目录里的脚本，可以在任务执行过程中由 Claude 调用，但 SKILL.md 本身只是文本。
从错误中学习
Custom Skills 不会在不同 surface 之间自动同步。你上传到一个 surface 的 skill，不会自动在其他 surface 上可用。更根本一点说，skill 也不会根据过去某次会话里发生了什么来更新自己。只要你不改它，指令就是静态的。我一直提醒自己记住这一点——skill 是一份被定格的经验，不是一个学习闭环。
自动跨 agents 或 sessions 共享
Skills 的作用域取决于它们被装在哪个 surface 上。一个在 Claude Code 里创建的 skill，不会自动出现在 Claude.ai 或 API 里，除非你另外再上传一次。
Skills、System Prompts、Project Rules 和 Memory 的区别
我在这里花的时间最多，也最容易绕晕。现在我是这样理解它们之间差别的：
| 机制 | 作用 | 范围 | 跨会话持久化？ |
|---|---|---|---|
| SKILL.md | 按需加载的领域专用指令 | Project 或 user-global | 是（基于文件） |
| CLAUDE.md | 始终加载的 Project 上下文与约定 | Project 级 | 是（基于文件） |
| System prompt | 设定模型的基础行为 | API/SDK 级 | 只有每次都设置时才是 |
| Projects (claude.ai) | 为持续进行的一项工作保存持久上下文 | Claude.ai workspace | 是 |
| Memory | 跨对话回忆偏好 | 用户级 | 是（若已启用） |
Skills 教 Claude how 去做一件事。一个 Project 里可以装着你整个产品发布的背景信息，而一个 skill 则可以教 Claude 你们团队的写作标准，或者代码审查流程。
CLAUDE.md 是 Claude 在每次对话开始时都会读取的特殊文件。你可以把 Bash commands、代码风格、workflow 规则都写进去。它给 Claude 提供的是那些单靠代码本身推不出来的持久上下文。它和 SKILL.md 的关键区别在于：CLAUDE.md 会 always 加载；skills 只在 when relevant 时加载。
Claude Code 的 system prompt 本来就已经包含大约 50 条独立指令。视模型不同而定，这差不多已经占掉 agent 能稳定遵循的指令总量的三分之一——还没算上 rules、plugins、skills 或 user messages。这个数字一直留在我脑子里。它会改变你对每一层该放多少内容的判断。
FAQ
1 官方的 Claude Code Skills documentation 在哪里？
最主要的参考资料是 Claude Code skills documentation。如果你想看更大的 Agent Skills 标准——包括 pre-built skills 和 custom skills 如何在 Claude.ai 以及 API 里运作——可以看 Anthropic 平台文档里的 Agent Skills overview。
2 SKILL.md 用的是什么格式？
SKILL.md 是一个带 YAML frontmatter 的 Markdown 文件。frontmatter 必须包含两个字段——name 和 description——Claude 会在 session 启动时读取它们，用来判断什么时候该加载这个 skill。Markdown 正文里放的，则是 Claude 在 skill 被调用时真正会遵循的指令。进阶一点的执行控制，还可以用 context 和 agent 这类可选字段。
3 SKILL.md 文件可以有多长？
没有强制的硬上限。让 Agent Skills 能同时保持灵活和可扩展的核心设计原则，就是渐进式披露——skills 让 Claude 只在需要时才加载信息，所以一个 skill 能打包进去的上下文，从理论上说几乎没有边界。即便如此，大多数更实用的建议仍然是：把核心 SKILL.md 控制在 500 行以内，把更细的内容拆到 references/ 里。
我到现在仍然不敢说，自己已经把这里所有的边角情况都画清楚了。skill 的触发行为——Claude 什么时候会判断一个 skill 相关，什么时候又不会——比格式文档让人以为的更难预测。Claude 有点容易对 skill “触发不足”——明明有用的时候却没用上。写 description 字段时，这点值得记住。
我会继续观察这件事怎么沉下来。
