一句话核心：Agent Skills 的开放规范把「一个 skill 长什么样」写成了可校验的硬约束——一个目录 + 一个 SKILL.md，frontmatter 里两个必填字段、四类可选字段，每个都有明确的字符数与命名规则；再叠加「渐进式披露」这条分层加载机制，它决定了你的 skill 是在帮 agent 省上下文，还是在挤占它。
这份规范管什么
skill 不是一个配置文件，而是一个目录。最小要求是目录里有一个 SKILL.md；此外可以放 scripts/（可执行代码）、references/（文档）、assets/（模板、图片、数据），以及其它文件或目录。SKILL.md 本身 = YAML frontmatter + Markdown 正文。
frontmatter 用 Markdown 书写，但字段约束是硬性的。下面逐字段拆开。
frontmatter 逐字段解读
| 字段 | 必填 | 约束 | 实操要点 |
|---|---|---|---|
name |
是 | 1–64 字符；仅小写字母 a-z、数字 0-9 与连字符 -；不能以连字符开头或结尾；不能出现连续连字符；必须与父目录同名 |
目录名与 name 不一致是最常见的校验失败 |
description |
是 | 最多 1024 字符、非空；要写清做什么与何时使用 | 它是唯一在启动时就被加载的字段（见下一节），写得含糊，agent 就不会选中你 |
license |
否 | 许可名称，或指向随包许可文件的引用 | |
compatibility |
否 | 1–500 字符；仅在有特定环境要求时填写（目标产品、系统依赖、网络需要等） | 官方明确：多数 skill 不需要这个字段 |
metadata |
否 | 字符串键值映射，用于补充自定义元数据 | |
allowed-tools |
否 | 空格分隔的预批准工具列表 | 官方标注为实验性，各客户端实现支持程度不一 |
渐进式披露：决定 skill 是否「挤占上下文」
官方把加载分成三层，这也是这份规范里最值得记住的机制：
- metadata（约 100 tokens）：
name与description在启动时对所有 skill 全量加载——也就是说，description 是唯一「每次请求都占预算」的内容。 - instructions（建议 < 5000 tokens）：
SKILL.md正文在 skill 被激活时才加载。 - resources：
scripts/、references/、assets/中的文件按需加载。
配套的两条结构要求同样来自官方：主 SKILL.md 控制在 500 行以内，超出部分拆到独立文件；文件引用保持距 SKILL.md 一层深，避免深层嵌套的引用链。
理解了这三层，就能明白为什么「把所有内容塞进主文件」和「引用套引用」会同时拖慢 skill 的触发与执行。
提交前自检清单
- 父目录名与
name完全一致（含连字符规则：不以连字符开头/结尾、无连续连字符） description同时写了「做什么」与「何时使用」，并包含帮助 agent 识别任务的词- 没有为不需要环境的 skill 硬加
compatibility - 使用
allowed-tools时清楚它是实验性字段，不作为依赖 - 主
SKILL.md未超过 500 行；详细材料已移到references/ - 文件引用只有一层深
- 跑一次官方校验：
skills-ref validate ./my-skill（检查 frontmatter 合法性并遵循上述命名约定）
辩证评估
- 价值：规范把原本靠口口相传的写法经验变成了可校验条款。对做多客户端适配的团队，一份符合规范的
SKILL.md能被所有遵循该标准的 agent 直接读取，不必为每个客户端维护一套。 - 最大的风险点恰恰是最小的字段：
description是唯一启动即加载的内容，也是路由的唯一依据。写得笼统，再强的脚本也不会被触发——而这个问题在语法校验里是看不出来的，它需要行为评测才能量出来。 - 规范只约束「长什么样」，不保证「有没有用」：命名合规、字段齐全，都不等于 skill 会被正确触发、更不等于它优于裸模型。
- 实验性字段不宜作为依赖：
allowed-tools的跨客户端支持程度不一致。 - 时效口径：规范页本身未标注发布日期，请把它当作「当前生效的规范」看待，而不是某个时点的新发布。
上手难度与推荐理由
- 上手难度：低。只需要一个目录加一个 Markdown 文件，校验是一条命令。
- 推荐理由：这是 agent skill 当前的通用格式规范；照着字段表和自检清单过一遍，能规避掉最常见的一类失败——skill 写了但 agent 不选它。它是「能否被识别」的门槛，也是后续做效果评测的前提。
官方来源
- Agent Skills 规范原文（目录结构、frontmatter 字段、渐进式披露、文件引用、校验）：Specification - Agent Skills