按 Agent Skills Specification 写 Skill：从 SKILL.md 到 scripts 的完整上手

按 agentskills.io/specification 的定义，怎样从 SKILL.md、frontmatter、scripts/、references/ 一路搭出一个标准 Skill。

先抓四个重点：

• Skill 的最小单元是目录，不是单文件 prompt

• SKILL.md 是入口文件

• name 和 description 决定这个 Skill 能不能被正确识别

• scripts/、references/、assets/ 决定它能不能长成可维护的真实能力

一、Skill 的最小单元是目录

按 Agent Skills Specification，一个 Skill 至少是一个目录，里面最少有一个 SKILL.md：

skill-name/

├── SKILL.md

├── scripts/

├── references/

├── assets/

└── ...

这里有两个要点：

• Skill 的最小单元是目录

• SKILL.md 是必须的，其他目录是可选的

Agent Skills Specification 对这些目录的定位也很清楚：

• scripts/：可执行脚本

• references/：按需加载的参考资料

• assets/：模板、图片、静态资源

只写一个 prompt 文本，没有目录、没有元数据、没有资源边界，这种形态更接近“随手记的模板”，离完整 Skill 还差一层结构。

二、SKILL.md 才是 Skill 的入口

Agent Skills Specification 要求 SKILL.md 由两部分组成：

1. YAML frontmatter

2. 后面的 Markdown 正文

最小例子是这样的：

---

name: skill-name

description: A description of what this skill does and when to use it.

---

这里写具体说明。

frontmatter 也是最常出问题的部分。

三、frontmatter 里有哪些核心字段

Agent Skills Specification 里，frontmatter 的核心字段有这些：

• name 必需。用来标识 Skill。

• description 必需。说明 Skill 做什么，以及什么时候该用。

• license 可选。记录技能许可信息。

• compatibility 可选。说明运行环境要求。

• metadata 可选。放自定义键值信息。

• allowed-tools 可选。预批准工具列表，属于实验字段。

如果想先做一个最小可运行版本，至少先把这两个字段写对：

• name

• description

1. name

Agent Skills Specification 对 name 限制得很严：

• 长度 1-64 个字符

• 只允许小写字母、数字、连字符

• 不能以连字符开头或结尾

• 不能有连续连字符

• 必须和父目录名一致

合法例子：

name: pdf-processing

name: code-review

name: data-analysis

不合法例子：

name: PDF-Processing

name: -pdf

name: pdf--processing

很多人写 Skill 第一步就错在这里： 目录叫一套，name 写另一套，或者带大写、空格、下划线。这样后面无论你正文写得多好，Skill 都已经不规范了。

2. description

description 也是必需字段，Agent Skills Specification 要求它同时描述两件事：

• 这个 Skill 做什么

• 什么时候应该触发它

一个好的写法通常会同时包含：

• 动作

• 场景

• 关键词

例如 Agent Skills Specification 里的好例子：

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

而这种写法就太弱：

description: Helps with PDFs.

因为它几乎没有提供触发线索。

四、什么时候该加 license、compatibility、metadata

这几个字段都属于可选项，在真实项目里很有用。

license

Skill 需要明确授权边界时，可以加：

license: Apache-2.0

或者：

license: Proprietary. LICENSE.txt has complete terms

compatibility

如果 Skill 对环境有明确要求，就应该写出来，例如：

compatibility: Requires git, docker, jq, and access to the internet

或者：

compatibility: Requires Python 3.14+ and uv

Agent Skills Specification 也说得很明确： 大多数 Skill 并不需要这个字段。 只有在环境前提真的重要时才加。

metadata

metadata 是一个字符串键值映射，适合放一些 Agent Skills Specification 没有正式定义、但客户端可能想读的信息，例如：

metadata:

author: example-org

version: "1.0"

它的定位是给客户端留扩展位。

allowed-tools

这是 Agent Skills Specification 里明确标出来的实验字段。

示例长这样：

allowed-tools: Bash(git:*) Bash(jq:*) Read

要注意两点：

• 它是可选

• 它的支持情况取决于具体 agent client

所以它可以写，但不能假定所有实现都会完全照着执行。

五、正文怎么写，Agent Skills Specification 给了很大自由度

frontmatter 之后的 Markdown 正文，Agent Skills Specification 本身没有强制格式。

只要它对 agent 真有帮助，就可以写进去。

Agent Skills Specification 推荐你优先写这些内容：

• 分步骤说明

• 输入 / 输出示例

• 常见边界情况

重点在这两件事：

• agent 读完之后能不能做事

• 触发后能不能少走弯路

这也意味着，Skill 正文不一定要写成某种固定模板。 你完全可以按任务来组织内容，只要它够清楚、够可执行。

六、scripts/、references/、assets/ 各自解决什么问题

很多 Skill 一开始会把所有东西都塞进 SKILL.md，结果文件越写越长，最后 agent 一激活就得把整份大文档全读进上下文。

Agent Skills Specification 给出的建议很明确： 把主入口和重资料分开。

scripts/

适合放：

• Python

• Bash

• JavaScript

这类可执行代码。

Agent Skills Specification 要求这些脚本：

• 依赖清楚

• 错误信息清楚

• 边界情况处理合理

scripts/ 要让 agent 能直接跑，跑坏了也看得懂。

references/

适合放按需加载的文档。

例如：

• REFERENCE.md

• FORMS.md

• 某个领域单独拆出的 finance.md、legal.md

Agent Skills Specification 推荐把参考资料拆小、拆专，原因很简单：

• agent 是按需读这些文件

• 文件越小，越省上下文

• 主题越单一，越容易在真正需要时命中

assets/

适合放静态资源：

• 模板

• 图片

• 查找表

• Schema 文件

如果一个 Skill 要生成固定格式文档、配置、封面或者结构化输出，assets/ 往往比把大段模板写进正文更稳。

七、Skill 设计的关键：渐进加载

Agent Skills Specification 里有一个特别值得记住的词：progressive disclosure。

核心意思是：

• 启动时，所有 Skill 只先暴露元数据

• 真正触发后，才加载 SKILL.md

• 再需要时，才继续读 scripts/、references/、assets/

文档里给了一个很清楚的三层结构：

1. 元数据：name + description

2. 主说明：SKILL.md

3. 资源文件：按需加载

这也是为什么 Agent Skills Specification 会建议：

• SKILL.md 控制在 500 行以内

• 详细资料拆到单独文件

• 不要做深层嵌套引用

如果一个 Skill 的主文件已经像一本小册子，那它的上下文成本大概率已经失控了。

八、文件引用怎么写才符合 Agent Skills Specification

Agent Skills Specification 对这一点也写得很具体：

• 在 SKILL.md 里引用其他文件时，使用相对路径

• 路径以 skill 根目录为基准

• 尽量保持一层引用，不要做深链条跳转

例如：

See [the reference guide](references/REFERENCE.md) for details.

或者直接写：

scripts/extract.py

这类路径足够简单，agent 更容易定位，也不容易因为目录层级太深而迷路。

九、一个最小可用 Skill

最小可用版本可以从下面这个结构开始：

code-review/

└── SKILL.md

SKILL.md 内容：

---

name: code-review

description: Review code changes for bugs, regressions, unsafe patterns, and missing tests. Use when the user asks for code review, diff review, PR review, or risk analysis on changes.

compatibility: Designed for coding agents with file read and diff access

---

## What to check

- logic defects

- behavioral regressions

- unsafe changes

- missing tests

## Output shape

1. List findings by severity

2. Include file references

3. Keep summaries short

这个版本已经符合 Agent Skills Specification 的最小要求：

• 目录名正确

• name 合法

• description 同时描述“做什么”和“什么时候用”

• 没有多余结构

等它稳定后，再继续往里加：

• references/

• scripts/

• assets/

十、直接用 Anthropic 的 skill-creator

Anthropic 官方 skills 仓库里已经放了一份专门的 skill-creator：

• 仓库路径：anthropics/skills/tree/main/skills/skill-creator

它适合直接拿来做 Skill 设计助手。

最简单的用法就是让它围着这几件事帮你推进：

1. 先说明你要做什么 Skill

2. 给它两到三个真实触发例子

3. 让它帮你收敛 name、description 和目录结构

4. 再让它检查要不要补 scripts/、references/、assets/

5. 最后回到本文这一套检查项，自己做验证

这样用的时候，重点盯三件事就够了：

• description 有没有把触发条件写清楚

• SKILL.md 有没有塞太多内容

• 资源该不该拆到外部目录

十一、记得跑验证

Agent Skills Specification 最后给了一个直接可用的验证方式：

skills-ref validate ./my-skill

它会检查：

• frontmatter 是否有效

• 命名规则是否符合要求

• 目录和 name 是否一致

这一步非常关键。 因为 Skill 很多问题都出在格式层。 如果不做验证，你很可能把一份看起来像 Skill 的文件交出去，结果客户端根本不认。

十二、写 Skill 时常见的误区

1. 把 Skill 写成一篇经验总结

Agent Skills Specification 想要的是：

• 可复用

• 可触发

• 可执行

它不想要的是：

• “我这次怎么解决了某个问题”的复盘故事

2. description 写得太短

像下面这种：

description: Helps with PDFs.

几乎等于没写。

3. SKILL.md 塞太多内容

把这些内容：

• 参考资料

• 模板

• 大段 API 细节

• 各种边界情况

都堆进 SKILL.md，很快就会失控。

4. 路径和命名不一致

比如：

• 目录叫 pdf-processing

• name 写成 pdf_tool

这类问题会直接让 Skill 不合规。

十三、总结

按 Agent Skills Specification 写 Skill，重点只有三件事：

1. 把目录结构搭对

2. 把 frontmatter 写对

3. 把大资料拆出去，主文件保持可触发、可执行

对已经在做 agent 工作流的人来说，Agent Skills Specification 的作用很直接：

把一个可复用能力整理成客户端能识别、agent 能触发、上下文成本也可控的 Skill。

Sources

• Agent Skills Specification: https://agentskills.io/specification

• Agent Skills Best Practices: https://agentskills.io/best-practices

• Agent Skills Optimizing Descriptions: https://agentskills.io/optimizing-descriptions

• Agent Skills Using Scripts: https://agentskills.io/using-scripts

• Anthropic skill-creator: https://github.com/anthropics/skills/tree/main/skills/skill-creator