Claude Code Skills 功能解析：它是什么，以及如何使用

嗨，我是 Lena。去年晚些时候，我和 Claude Code 打交道的方式，悄悄发生了一点变化。我本来没打算注意到它，只是单纯想别再反复解释同样的事情。每次开新会话，我都会把同样的内容重新说一遍：我们的错误格式约定、commit messages 喜欢怎样组织、Python libraries 应该优先选哪些。Claude 每次都会理解并给出合适响应，然后到了下一次会话，又把这一切忘掉。那不算失败，更像是每一次都得从同一个起点重新开始。

然后我开始认真看 Claude Code Skills 这个功能，某些东西就微妙地变了。

什么是 Claude Code Skills 功能？

SKILL.md 到底是什么

从最简单的角度说，一个 skill 就是一个目录，里面放着一个 SKILL.md 文件。它本质上是一个组织好的指令、脚本和资源文件夹，Agent 可以动态发现并加载它，从而在特定任务上表现得更好。

这个文件分成两部分：最上面是 YAML frontmatter（位于 --- 标记之间），下面是 markdown instructions。name 字段会变成斜杠命令，description 则帮助 Claude 判断什么时候该自动加载这个 skill。

实际看起来大概是这样：

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

嗯，好吧。所以它并不是什么魔法。本质上，它就是一个结构化文本文件，Claude 会在合适的时刻把它读进来。

Skills 和 system prompts、project rules 有什么不同

这一点我一开始也有点拿不准。

不同于 prompts 这种只面向单次任务的 会话级指令，Skills 是按需加载的，它解决的是你不必在多次对话中重复提供同样指导信息的问题。真正关键的差别在于 加载时机。system prompt 是一直都在的；skill 则静静待在文件系统里，只有当 Claude 判断它和你正在做的事情相关时，才会被拉进上下文。

这个设计让我觉得很有意思的一点在于：它实现了一种按需扩展 prompt 的方式，却不需要改动核心 system prompt。Skills 更像是可执行的知识包，Claude 只在需要时才加载它们，从而扩展能力，同时让主 prompt 保持精简。

这对我来说是个很有分量的区别，虽然我现在还是没完全弄清 Claude 到底在什么时刻才会判定“相关”。

如何使用 Claude Code Skills

SKILL.md 文件应该放在哪里

Skills 会从多个来源被发现并加载。Claude Code 会扫描用户级设置（~/.claude/skills/）、项目级设置（.claude/skills/）、插件提供的 skills，以及内置 skills，从而构建出可用 skills 列表。

所以，用户级 skills 放在 ~/.claude/skills/skill-name/SKILL.md。项目级 skills 放在仓库里的 .claude/skills/skill-name/SKILL.md。每个 skill 都需要一个单独的命名子目录。定义在 .claude/skills/ 下、且目录是通过 --add-dir 加入的 skills，会被自动加载，并支持实时变更检测，所以你甚至可以在会话中途直接编辑它们，而不用重启。

最后这一点，也就是 会话中途修改而不用重启，我当时完全没想到。这意味着你可以在任务进行到一半时调整 skill，然后立刻观察变化。我觉得这点很值得留意。

Claude 会遵循什么样的指令

skill 文件里几乎什么指令都能放，但如果你先想清楚自己打算如何调用它，通常会更容易决定该写什么。参考型内容提供的是 Claude 应用于当前工作的知识，比如约定、模式、风格指南、领域知识。任务型内容则是针对具体动作的分步说明，比如部署、提交，或者代码生成。

你还可以把辅助文件一起打包进去。Claude 可以执行的 scripts、它可以填写的 templates，以及只在需要时才加载的 reference 文档。Claude 会按需分阶段加载信息，而不是一开始就把上下文吃满，这是一种渐进式披露模式。 所以，一个 skill 完全可以比单个文件丰富得多，同时又不必在每次会话里都占满 context window。

如何验证 skill 是否真的被应用了

这部分我到现在还是觉得有点模糊。

根据 official Claude Code skills documentation，决定自动触发的是 description 字段：Claude 会在启动时读取所有可用 skill 的描述，并用它们来判断什么时候调用某个 skill。对 200+ 个 prompts 的真实测试显示，激活可靠性差异很大。优化过的 description 可以把触发率从 20% 提高到 50%，如果再加上 examples，甚至可以进一步提升到 90%。

所以，如果某个 skill 没被触发，通常最先值得回头重写的就是 description。写得更具体一点，把触发条件写得更直白一点。Anthropic skills GitHub repository 也明确提到过这一点：Claude 往往更容易触发不足，因此 description 语言最好对 什么时候该激活 说得略微直接一些。

Skills 擅长做什么

编码项目约定

这时我才开始更清楚地看到它的价值。如果你的团队有一套固定模式，比如 API 响应该怎么组织、错误对象该长什么样、异步流程应该怎么处理，你可以把这些一次性写进 skill 里，从此不用每次都重新解释。

给 Agent 写一个 skill，有点像给新来的同事准备一份入职指南。这个比喻我觉得很贴切。它不是永久记忆，更像是一张 Claude 随手可取的参考单。

可重复的输出格式

那些基于任务的 skills，也就是通过斜杠命令调用的那种，很适合处理提交信息生成、PR 描述、部署清单之类的任务。它们擅长的是把输出的 形状 固定下来，而不只是提供泛泛的指导。

给 Claude 注入领域特定上下文

Skills 通过把你的专业知识打包成可组合资源来扩展 Claude 的能力，让通用 Agent 逐步变成真正贴合你需求的专用 Agent。对于那些工作在细分技术领域里的团队，比如自定义 DSL、内部工具链或特殊合规规则，这件事开始变得非常有用。

Skills 做不到什么

没有跨会话学习

Skills 不会自己更新。它们不会观察什么做法有效，然后回头改写自己的指令。一次会话开始时，SKILL.md 里写了什么，Claude 就照着什么工作，除非你手动去改。Anthropic engineering blog on Agent Skills 说得很直接：“Iterate with Claude — as you work on a task with Claude, ask Claude to capture its successful approaches into the skill.” 这里的 capture 仍然是人的动作，不是 Claude 自动完成的。

没有执行反馈闭环

如果 Claude 运行某个 skill 后给出了错误结果，这个 skill 本身不会因此更新。没有任何信号会回流到这套指令里。无论上次发生了什么，下次仍然会套用同样的指导。

无法在团队或 Agent 之间自动共享

Custom skills 是每个用户各自拥有的，它们不会在组织范围内自动共享，也不能被管理员集中管理。一个开发者写出来的 skill，不会自动传播到队友的环境里。它要么留在本地，要么放进项目目录，再靠手动方式共享出去。

这一点我一直在反复想。定义一致 Agent 行为的能力是真实存在的，但分发问题仍然没有被解决。

静态 Skills 之后是什么

从基于文件的指令，到可验证、可继承的能力

Skills 这个功能确实解决了一个真实问题：重复解释上下文。你不再需要一遍遍重说，而是开始把它编码下来。

但我一直反复注意到一个空缺。一次成功修复、一套来之不易的调试模式、一串终于稳定起作用的 prompt sequence，这些经验还是不会流动。它们留在某次会话里，或者最多在有人记得时，被手动整理回 SKILL.md。

这背后其实有个更大的问题，我还在试着把它表达清楚。大概是 被给出的指令 和 在很多 Agent 身上都被验证过的行为 之间的差别。Skills 属于前者。它们设计得很好，可组合，也确实有用。但它们依然是静态工件，由人创建、由人维护，而且作用域局部。

如果一种成功方法可以被浮现出来、被验证，再被提供给其他遇到相似问题的 Agent，会是什么样？那已经是另一类基础设施问题了。skills 格式本身并不回答这个问题，而且它大概也没打算回答。

……我还会继续想这个问题。

FAQ

1. Claude Code 里的 Skills 功能是什么？ claude code skills feature 让你通过结构化的 SKILL.md 文件扩展 Claude 的行为。每个文件都包含 YAML frontmatter 和 markdown instructions；当任务与 skill 的 description 匹配时，Claude 会动态加载它。
2. 我该如何为 Claude Code 创建一个 SKILL.md 文件？ 在 .claude/skills/your-skill-name/ 下创建文件夹，然后在里面添加一个 SKILL.md 文件。先写 YAML frontmatter（name 和 description 是必需项），再写 markdown 指令。Anthropic skills repository 里有一个 template-skill 可作为起点。
3. Claude Code Skills 会在会话之间持续生效吗？ 持续存在的是这个 文件。Claude 对它的使用记忆不会保留。每次会话里，Claude 都会重新读取 skill 的 description 和 instructions。内置的跨会话学习并不存在。
4. 我可以把 Claude Code Skills 分享给团队吗？ 你可以手动共享 skill 目录，比如通过仓库里的 .claude/skills/ 文件夹，或者借助支持跨平台可移植性的 Agent Skills 开放标准。但目前还没有组织级的自动同步机制。
5. Claude Code Skills 和项目规则有什么区别？ 项目规则（比如 CLAUDE.md）配置的是某个项目的整体行为。Skills 则是模块化、面向具体任务的能力包。它们会根据 Claude 正在做什么而有条件地加载，而不是始终常驻上下文。你可以把 CLAUDE.md 理解为环境级指令，把 skills 理解为按需调用的专长。