去年底我们团队开始用 Skills 的时候，有个人做了一个“全能测试 Skill”，把登录、下单、支付、退款全写进一个 SKILL.md 里，洋洋洒洒六百多行。跑的时候确实能工作，但每次都要加载全部内容，改一个支付逻辑要翻半天文档，想复用其中的登录步骤——不好意思，拆不出来。
这不是个例。很多人把 Skill 当“超级提示词模板”用，往一个文件里塞越多越好。本质上，他们把 Skill 当成了脚手架——一次性搭起来用完就拆的东西。
但 Skill 不是脚手架。它是可复用、可组合、可演进的能力单元。读不懂 SKILL.md 和仓库结构的设计意图，你就永远在“写提示词”而不是“构建能力”。
目录
一、SKILL.md 正在成为 Agent 时代的“接口定义文件”
二、本质不是提示词模板，是能力封装单元
三、拆解 SKILL.md：元数据是门面，正文是手册
四、拆解仓库结构：scripts、references、assets 各司其职
五、一个错误案例 vs 一个正确案例
六、对你意味着什么
七、最后问你一个问题
一、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 越来越臃肿，加载越来越慢，复用越来越难。
可以被截图传播的观点句 1：Skill 不是写出来的，是设计出来的。SKILL.md 不是提示词，是接口定义。
二、本质不是提示词模板，是能力封装单元
先看一个基础事实。
一个 Skill 本质上就是一个包含 SKILL.md 文件的文件夹。SKILL.md 使用 YAML frontmatter + Markdown 正文的格式。
但“本质上是什么”和“实际该怎么用”是两回事。
很多人把 Skill 当成“高级提示词模板”——把原本要复制粘贴给 AI 的一大段话，放进一个文件里，然后让 AI 自动读取。
这个理解只对了一半。
Skill 和提示词模板的核心区别在于三点。
第一，Skill 是可发现的。 Agent 启动时只加载所有 Skill 的元数据（name 和 description），而不是完整内容。AI 通过元数据判断“这个 Skill 跟我当前的任务有没有关系”，有关系才加载正文。提示词模板没有这个发现机制——你得手动选、手动贴。
第二，Skill 是可组合的。 一个 Skill 可以调用另一个 Skill 的输出，可以串联成工作流。提示词模板之间没有这种依赖关系。
第三，Skill 是可版本化的。 Skill 就是文件夹里的文件，可以 Git 管理、可以 Code Review、可以 CI 校验。提示词模板散落在聊天记录和文档里，没人管版本。
本质上，Skill 解决的是能力复用的问题——把“怎么做一件事”固化成可被 AI 自动发现、自动加载、自动执行的标准模块。
可以被截图传播的观点句 2：提示词模板是给人看的说明书，Skill 是给 AI 用的能力包。两者差了一个工程化的维度。
三、拆解 SKILL.md：元数据是门面，正文是手册
3.1 YAML frontmatter：决定 AI 会不会用你
SKILL.md 的开头是 YAML frontmatter，用 --- 包裹。
最少需要两个字段：
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 的“操作手册”。
正文写什么？核心就三件事：
目标与边界：这个 Skill 做什么、不做什么
执行步骤：具体的操作流程，可以是线性步骤、决策树或循环迭代
输入输出规范：需要什么数据、产出什么结果
正文应该尽量精炼。不是把所有能写的都写进去，而是只写 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、JavaScript 等。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 当成“可组合的乐高积木”。
可以被截图传播的观点句 3：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，是能力单元还是长提示词？留言聊聊你的判断。
