大家好，我是 Lena。2025 年末，有些东西在安静地变了。我不是一下子察觉到的，它来得很慢，就像大多数真正的变化一样。
我一直在观察 Claude Code 如何在不同项目间处理重复任务。那个模式我太熟悉了：同样的指令，每次都要用略微不同的方式重写；同样的上下文，每次都要重新解释一遍。我开始觉得缺的不是模型本身，而是 模型与具体工作之间的那一层。
现在，这一层有名字了。它叫 Claude Code Skills。
什么是 Claude Code Skills？
从最简单的层面看，一个 Claude Code skill 就是一个文件夹。这个文件夹里有一个叫 SKILL.md 的文件。当 Claude Code 发现这个目录时，它会读取该文件，把里面的指令加载进上下文，并据此调整自己的行为。
我反复回到这个定义，是因为它听上去几乎简单得过头了。但只要你愿意多想一会儿，它背后的含义会比一开始看见的更大。
Skills 不是你每次对话开头都要手动粘贴的 prompts。它们是 可复用的行为包，Claude 会自动发现并在相关时机应用。你安装一次，Claude 就会在需要时把对应上下文调出来，而不用你反复提醒。
SKILL.md 格式是怎么工作的
每个 skill 都从同一套两段式结构开始。SKILL.md 是一个两段式的 Markdown 文件：前半段是 frontmatter，后半段是正文内容。frontmatter 负责配置 skill 如何 运行（权限、模型、元数据），而 markdown 正文则告诉 Claude 该做什么。
最小示例如下：
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude will follow when this skill is active]
name 字段会变成斜杠命令。description 字段则是 Claude 在判断是否要加载这个 skill 时首先读取的内容。这个 description 对 skill 选择至关重要：Claude 会凭它从可能多达 100+ 个可用 skills 里挑出合适的那个。你的 description 必须给出足够细节，让 Claude 明白 什么时候 该选用这个 skill；至于其余实现细节，则放在 SKILL.md 的主体里。
这一点其实很容易被低估。我前几次尝试时就做错了：我写的 description 在技术上没错，但在行为触发上太含糊。结果要么 skill 在不该加载的时候被加载，要么根本不加载。description 不是单纯的元数据，它本质上是一个路由决策。
如果你想看完整规范，可以直接阅读 official Claude Code Skills documentation。
你可以编码哪些行为
从这里开始事情才真正变得有意思。Skills 并不局限于文本说明。每个 skill 都是一个目录，里面除了主 SKILL.md 文件外，还可以包含供 Claude 填写的模板、展示期望格式的示例输出，以及 Claude 可以执行的脚本。
在实践里，这意味着你可以编码：
- 编码约定 — 团队如何命名函数、如何组织测试、如何处理错误
- 工作流模式 — Claude 在生成报告或处理文件时应该遵循的多步流程
- 可执行脚本 — 确定性的校验逻辑、文件转换、外部 API 调用
- 参考文档 — Claude 按需读取的详细规范，不用把每次会话都塞得很满
关键的设计点在于：当一个 skill 被触发时，Claude 会用 bash 从文件系统里读取 SKILL.md，把里面的指令带进 context window。如果这些指令又引用了其他文件，Claude 也会继续去读它们。若说明中提到了可执行脚本，Claude 会运行脚本，并只拿到输出结果，脚本代码本身不会进入上下文。
这点很细，却很重要。skill 是 按需懒加载 的。你完全可以把一份 50 页的参考文档打包进 skill 里，而 Claude 只会拉取它真正需要的部分。
构建你的第一个 Claude Code Skill
说实话，我写的第一个 skill 并不好。倒不是坏掉了，而是……不够精确。它的触发范围太宽，指令会和当前对话抢控制权，我花在解释“我到底想要什么”上的时间，甚至比我直接自己打出来还多。
如果再来一次，我会这样做。
文件放置与格式
对 Claude Code 来说，skills 放在项目目录里的 .claude/skills/，或者全局生效的 ~/.claude/skills/。Claude Code 目前只支持 Custom Skills，所以 skill 的创建方式就是一个目录加一个 SKILL.md 文件。
文件夹名就是这个 skill 的身份。尽量用小写和连字符。目录结构通常像这样：
my-skill/
├── SKILL.md ← required
├── examples/ ← optional but helpful
│ └── sample.md
└── scripts/ ← optional
└── validate.sh
SKILL.md 的 frontmatter 必须有两个字段：name 和 description。name 只能使用小写字母、数字和连字符。description 则最好始终用第三人称来写，因为这段描述会被注入 system prompt，视角不一致时容易影响 skill discovery。
如何验证你的 Skill 是否真的被应用了
我一开始也被这个问题困住过。界面里并没有明确的“skill 已加载”提示。后来我找到最实用的办法是直接问 Claude：“What skills do you have access to?” 它通常会把列表说出来。你也可以看 Claude 在那些本应触发 skill 的任务上，行为有没有发生变化。
更可靠的验证方式还是看行为：让 Claude 在有 skill 和没有 skill 的情况下完成同一任务。如果输出模式确实朝你编码的方向变化了，说明 skill 起作用了。理解触发机制也有助于设计更好的 skills。Skills 会以名称和 description 的形式出现在 Claude 的可用 skills 列表里，Claude 会基于 description 判断是否要调用某个 skill。对于它本来就能轻松处理的简单单步任务，即便 description 匹配，Claude 也未必会去 consult 这个 skill。
Skill 设计中最常见的错误
Anthropic skill authoring best practices guide 已经总结得很好了，但我最常见到的几类问题是：
- description 太模糊 — Claude 不理解 skill 的边界，就无法稳定地路由到它
SKILL.md塞得过满 — 别试图把所有东西都塞进一个文件，细节请拆到引用文档里- 没有示例 — 没有具体示例的 skill，输出往往更不稳定
- 指令过时 — 不要把很快就会过期的信息直接写死进去；如果是版本相关说明，最好放在可折叠区块里，或者明确标上日期
在项目与团队之间共享 Skills
这时事情开始真正变得有用，但同时，当前的限制也会被看得更清楚。
SKILL.md 共享的当前限制
Skills 仍然是基于文件分发的。这意味着共享它们，本质上还是共享文件：打包 zip、放进 Git 仓库，或者手动复制。现在的分发模型要求用户自己把 skill 文件夹下载下来，再放到 Claude Code 的 skills 目录里。组织级 skills 则可以由管理员在整个工作区范围内部署，这项能力在 2025 年 12 月上线，支持自动更新和集中管理。
这已经是一次很有意义的改进了。但它仍然意味着 skill 是一个静态工件。当它编码的底层工作流发生变化时，skill 不会自己更新。总要有人去维护它。
2025 年 12 月，Anthropic 把 Agent Skills 规范发布成了开放标准，OpenAI 也在 Codex CLI 中采用了同一种格式。Skills 是 model-invoked 的，也就是说 AI 会基于上下文自动决定何时使用它们。这种互操作性是真实而有价值的。你为 Claude Code 写的 skill，原则上也可以运行在 Cursor 或其他兼容环境里。你可以浏览 Anthropic skills GitHub repository，看看社区已经贡献了哪些例子。
跨 Agent 共享层可能长什么样
这一部分我还在继续摸索。
现在，一个 skill 是由人编写、由人审阅、再手动分发的。Agent 会执行它，但不会改进它。它不会从结果里学习，不会传播成功的变体，也不会在说明与真实有效做法逐渐漂移时发出提醒。
如果真要有一层跨 Agent 的共享机制，它需要的不止这些：执行验证、质量评分、版本演进脉络。静态的 SKILL.md 很擅长表达 意图，但并不记录 结果。
我还没见过哪里把这个问题真正解决得很干净。
天花板：Claude Code Skills 到哪里就不够用了
静态文件 vs. 自适应学习
Skills 是指令。它们不会观察自己的表现。如果一个 skill 编码了一种六个月前还很有效的调试模式，但后来因为模型更新或 API 变化而不再那么可靠了，skill 自己不会知道。最终察觉到变化的，还是你。
Skills 是活文档，需要随着时间根据实际表现持续迭代。这当然是好建议，但这也意味着迭代负担完全落在作者身上。Agent 本身无法参与修正自己正在遵循的那份说明。
没有执行验证，也没有修复闭环
当一个 skill 被执行后，如果结果错了，skill 机制本身不会捕获这件事。Claude 只是照着 SKILL.md 去做。如果结果没有贴合最初意图，这个闭环不会自动补上。
对于那些编码稳定约定的 skill，比如代码风格或文档结构，这个问题没那么大；但对于编码动态工作流、而正确性又强烈依赖具体任务的 skills，这就会变成更明显的问题。
没有复用网络
今天的 skills 要么是本地的，要么是公开放在 GitHub 上的。还没有一种“环境层”，可以让某类问题的成功解法，在经过测试、验证、版本追踪之后，被其他面临相似问题的 Agent 发现并继承。
SkillsMP community marketplace 算是朝这个方向迈出的早期一步。它对发现别人做了什么很有帮助。但它收录的 skills 依然是静态文件。它们没有审计记录，不知道自己被应用了多少次，也不知道结果如何。
Skills 之后是什么
从静态指令到可验证、可继承、可交易的能力
这个问题我已经想了好一阵子。
Claude Code skills 解决的是一个真实问题：它让 Agent 的行为变得可重复、可迁移。这一点并不小。没有 skills 之前，上下文必须在每次会话里重新建立。现在不必了。
但 skill 仍然是人写出来的工件。它记录的是某个人 认为 有效的东西，而不是在什么条件下、以什么失败模式、究竟 真正有效 过的东西。
下一层形态，不管它最终长成什么样，可能都更像一种带来源可追溯性的能力，而不是单纯的文件格式。它会说：这种方法在这些条件下被尝试过，成功率是多少，在这些边界场景里失败过，由哪些作者修订过，又被哪些 Agent 在相近情境下实际使用过。
那就已经不是一个 markdown 文件能描述完的基础设施了。
我还没有完全想明白这条裂缝意味着什么。但它看起来并不偶然，更像是下一件值得持续观察的事。
FAQ
- Claude Code 里的
SKILL.md文件是什么？
SKILL.md 是每个 Claude Code skill 必需的主说明文件。它采用两段式结构：YAML frontmatter 用来告诉 Claude 什么时候该使用这个 skill，markdown 正文则是 Claude 在 skill 被调用时要遵循的指令。你可以把它理解成一份 onboarding 文档，只不过 Agent 不会忘记它。
- 我该如何编写一个 Claude Code skill？
先写 frontmatter：name（全小写，只能用连字符）和 description（用第三人称，明确写出何时触发）。然后在 markdown 正文中写清晰、直接的操作指令。只有在它们确实能改进行为时，再补充 supporting files，比如 examples、scripts 或 reference files。最好的测试方式，是比较同一任务在有无 skill 时的输出差异。更详细的写法可以参考 Anthropic's skill authoring best practices。
- Claude Code skills 可以在团队成员之间共享吗？
组织管理员现在可以在整个工作区范围内部署 skills，并支持自动更新和集中管理，这项能力已在 2025 年 12 月上线。对开源共享来说，GitHub 仍然是当前主要的分发渠道。Agent Skills 开放标准意味着为 Claude Code 编写的 skills 也可以运行在其他兼容工具中。互操作性已经存在；至于带执行历史的集中复用网络，仍然是一个开放问题。
我会继续观察这件事怎么发展。这里确实正在发生什么，我只是还没完全看清它会走到哪里。
