Skill 不是脚手架：读懂 SKILL.md 和仓库结构的正确姿势

好的，没问题。作为一名在AI工程化领域摸爬滚打多年的老手，我来帮你把这篇关于Agent Skills的文章，改得更像那么回事儿。 *** 去年年底，我们团队刚开始鼓捣 Agents Skills 那会儿，有个兄弟整了个“全能测试 Skill”，把登录、下单、支付、退款这些流程一股脑全塞进一个 `SKILL.md` 里，好家伙，洋洋洒洒六百多行。你别说，跑起来还真能用。但每次加载都得把整个文件吞进去，改个支付逻辑得翻半天文档，想复用里面的登录步骤？不好意思，根本拆不出来。 这事儿还真不是个例。很多人把 Skill 当成“超级提示词模板”来用，觉得往一个文件里塞得越多越牛。本质上，这是把 Skill 当成了临时脚手架——用完就拆，一次性的。 但 Skill 压根儿就不是脚手架。它应该是可复用、可组合、可演进的能力单元。如果读不懂 `SKILL.md` 和它背后仓库结构的设计意图，那你永远只会停留在“写提示词”的层面，而不是在“构建能力”。 ## 一、SKILL.md 正在成为 Agent 时代的“接口定义文件” 2025年10月，Anthropic 推出了 Agent Skills 的概念。到了同年12月18日，它被正式确立为跨平台的开放标准。 短短几个月，Claude Code、OpenCode、Cascade 这些主流的 Agent 框架就已经纷纷接入了这个格式。Anthropic 官方也开源了16个生产级的技能库，涵盖文档处理、创意设计、开发技术等各种领域。 这意味着什么呢？ 可以这么说，**SKILL.md 正在成为 Agent 时代的“接口定义文件”**——就像当年 OpenAPI 之于 REST API，proto 文件之于 gRPC。它定义了一个 Agent 能力模块的边界、入口和调用方式。 但可惜的是，很多人还在用写 Prompt 的思路来写 SKILL.md。恨不得把想到的一切都塞进去，生怕 AI 漏掉什么信息。结果就是：Skill 越来越臃肿，加载越来越慢，复用越来越难。 这里有一个核心观点值得记住：**Skill 不是写出来的，是设计出来的。SKILL.md 不是提示词，是接口定义。** ## 二、本质不是提示词模板，是能力封装单元 我们先把基础事实摆清楚。 一个 Skill 的本质，就是一个包含 `SKILL.md` 文件的文件夹。这个文件用的是 YAML frontmatter 加 Markdown 正文的格式。 但“本质是什么”和“实际该怎么用”，这完全是两码事。 很多人把 Skill 当成“高级提示词模板”——就是把原本要复制粘贴给 AI 的一大段话，放进一个文件里，然后让 AI 自己去读。 这个理解，只能说对了一半。 Skill 和提示词模板，核心区别在于三点： * **第一，Skill 是可发现的。** Agent 启动时只加载所有 Skill 的元数据（也就是 name 和 description），而不是完整内容。AI 会根据元数据来判断“这个 Skill 跟我当前的任务有没有关系”，有关系才会加载正文。提示词模板可没有这个发现机制——你得手动选、手动贴。 * **第二，Skill 是可组合的。** 一个 Skill 可以调用另一个 Skill 的输出，多个 Skill 可以串联成一个工作流。提示词模板之间可没有这种依赖关系。 * **第三，Skill 是可版本化的。** Skill 就是一个文件夹里的文件，可以用 Git 管理，可以做 Code Review，可以跑 CI 校验。而提示词模板呢？散落在聊天记录和文档里，谁管它版本不版本。 总结一下，Skill 解决的核心问题就是能力的复用——把“怎么做一件事”固化成能被 AI 自动发现、自动加载、自动执行的标准模块。 这里再强调一个观点：**提示词模板是给人看的说明书，而 Skill 是给 AI 用的能力包。两者之间，差了一个工程化的维度。** ## 三、拆解 SKILL.md：元数据是门面，正文是手册 ### 3.1 YAML frontmatter：决定 AI 会不会用你 `SKILL.md` 的开头就是 **YAML frontmatter**，用三个短划线 `---` 包裹起来。 最少需要两个字段： ```yaml --- name: api-test-generator description: 根据 OpenAPI/Swagger 文档自动生成 API 测试用例。当用户提到"接口测试"、"API测试"、"生成测试用例"时使用。 --- ``` * `name` 是 Skill 的唯一标识符，必须和文件夹名称保持一致。 * `description` 是 AI 判断“要不要加载这个 Skill”的核心依据。AI 启动时只看到这个 description，正文是看不到的。**description 写不好，Skill 永远不会被加载。** 好的 description 长什么样？ * 包含触发短语：把用户可能说的话写进去。 * 定义使用场景：说明什么时候该用，什么时候不该用。 * 包含关键词：让 AI 在语义匹配时能轻松命中。 而差的 description 往往只有一句话，比如“帮助做 API 测试”。这样AI根本不知道什么时候该调用它。 除了这两个必填字段，还有一些可选的扩展字段，比如 `allowed-tools`（声明需要的工具权限）、`references`（声明最重要的参考文档）等。 ### 3.2 Markdown 正文：让 AI 知道怎么执行 frontmatter 之后就是 **Markdown 正文**，这是 Skill 的“操作手册”。 正文写什么？核心就三件事： 1. **目标与边界**：这个 Skill 做什么、不做什么。 2. **执行步骤**：具体的操作流程，可以是线性步骤、决策树，也可以是循环迭代。 3. **输入输出规范**：需要什么数据，产出什么结果。 正文要尽量精炼。不是把所有能写的都写进去，而是**只写 AI 必须知道的执行逻辑**。那些更长的参考资料，应该放到 `references/` 目录下，按需加载。 ### 3.3 渐进式披露：三层加载模型 这是 Skill 设计里最核心的机制。  这个设计解决了什么问题？ * **上下文不膨胀**：即使你有几十个 Skill，初始也只加载元数据，不占用上下文。 * **加载更精准**：只加载当前任务相关的 Skill 内容。 * **支持海量信息**：Skill 可以包含大量脚本和文档，但只在需要时才加载。 很多人习惯把几百行内容全塞进 `SKILL.md` 正文里，这恰恰破坏了渐进式披露的设计意图。**正确的做法是：正文只写核心执行逻辑，细节放到 references，脚本放到 scripts。** ## 四、拆解仓库结构：scripts、references、assets 各司其职 一个标准的 Skill 仓库，结构应该是这样的： ``` my-skill/ ├── SKILL.md # 必需：元数据 + 核心指令 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档、规范、知识材料 └── assets/ # 可选：模板、图片、资源文件 ``` 每个目录都有它明确的职责： * `scripts/` 存放可执行脚本——Python、Bash、Ja vaScript 等。Agent 可以直接运行这些脚本，把结果拿回上下文。脚本代码本身不占用上下文 token，只有执行结果进入上下文。**这是 Skill 承载“确定性能力”的关键**——复杂的计算、数据清洗、文件操作，交给脚本去做，而不是让 AI 凭感觉猜。 * `references/` 存放参考文档——详细的规范、长篇的风格指南、政策文档等。这些内容只在需要时才被引用加载。**不要在 `SKILL.md` 正文里塞几千字的规范**，放进 references，按需取用。 * `assets/` 存放静态资源——模板文件、图片、样例数据等。Agent 生成内容时可以直接引用这些模板。 这三层目录加上 `SKILL.md` 本身，就构成了一个完整的“渐进式披露”体系： * `SKILL.md` 元数据 = 第一层（发现） * `SKILL.md` 正文 = 第二层（执行） * `scripts/references/assets` = 第三层（按需加载的深层资源） **目录结构不是装饰，它是渐进式披露的物理载体。** ## 五、一个错误案例 vs 一个正确案例 ### 错误案例：把 Skill 当脚手架 有个团队写了一个“电商全流程测试 Skill”，`SKILL.md` 正文足足600多行，包含了登录、搜索、加购、下单、支付、退款的全部步骤描述和断言规则。 这会导致什么问题？ * 每次加载都要消耗大量 token，即使你只想测登录，也得把整个文件加载一遍。 * 支付接口变了，你得在一大段文字里大海捞针般地找到对应的描述位置。 * 想单独复用“登录”这一步？拆不出来，因为它和其他步骤已经耦合在一起了。 ### 正确案例：把 Skill 当能力单元 另一个团队的做法是把它拆成了6个独立的 Skill： ``` login/ # 只描述登录 ├── SKILL.md add-to-cart/ # 只描述加购 ├── SKILL.md create-order/ # 只描述下单 ├── SKILL.md ... ``` 每个 `SKILL.md` 正文控制在50-80行，只写本 Skill 的核心逻辑。通用的校验规则放在 `references/`，可复用的脚本放在 `scripts/`。 效果立竿见影： * 每个 Skill 加载飞快，token 消耗低。 * 改支付逻辑，只需要改 `payment/` 这一个文件夹。 * 6个 Skill 可以任意组合，应对不同测试场景。 核心区别在于：**错误案例把 Skill 当成“一次性搭好的完整流程”，而正确案例把 Skill 当成“可自由组合的乐高积木”。** 这里同样有一个值得记住的观点：**Skill 的粒度应该小到你可以确信它只做一件事，并且这件事可以被其他 Skill 复用。** ## 六、对你意味着什么 ### 对在校生 你现在看到的 `SKILL.md` 格式，正在成为 Agent 生态的“通用语”。就像几年前学会 JSON 和 YAML 是基本功一样，理解 `SKILL.md` 的结构设计——元数据驱动发现、渐进式披露、目录分层——会让你在未来两三年里，比别人更早看懂行业的变化方向。你不需要写得多好，但需要看得懂，并且知道“为什么这么设计”。 ### 对初级工程师 你可能已经在用现成的 Skills 了。但如果你只会用、不会写，或者只会往一个 `SKILL.md` 里堆内容，那你还没真正掌握这个工具。真正的核心能力不是“写提示词”，而是“做封装设计”——判断一个能力的边界在哪里、应该拆多细、哪些内容放正文、哪些放 references。这个能力，比会写代码更重要。 ### 对中级工程师 你面临的问题是团队级别的 Skill 资产管理。当团队里有了几十个 Skill 时，怎么保证它们不冲突、可组合、可演进？答案在于**契约设计**——每个 Skill 的输入输出要明确，依赖关系要清晰，目录结构要统一。把这些规范沉淀下来，比写20个 Skill 更有价值。 ## 七、最后，不妨问问自己 现在就打开你最近写的一个 `SKILL.md`，看一眼它的正文长度。 如果超过了200行，问自己一个问题：这里面有多少内容是“核心执行逻辑”，有多少是“参考信息”？ 如果参考信息占了大部分，那说明你其实没在用 Skill 的渐进式披露能力——你只是在写一个长文本提示词，然后给它披上了 `SKILL.md` 的外衣。 你现在的 Skill，究竟是能力单元，还是长提示词？