格式规范
Agent Skills 的完整格式规范。
目录结构
Skill 是一个目录,至少包含一个 SKILL.md 文件:
skill-name/
├── SKILL.md # 必需:元数据与指令
├── scripts/ # 可选:可执行代码
├── references/ # 可选:文档
├── assets/ # 可选:模板、资源
└── ... # 其他任意文件或目录SKILL.md 格式
SKILL.md 文件必须以前置元数据(YAML frontmatter)开头,后接 Markdown 正文。
前置元数据
字段 | 是否必需 | 约束 |
|---|---|---|
| 是 | 最多 64 个字符。仅限小写字母、数字和连字符,不得以连字符开头或结尾。 |
| 是 | 最多 1,024 个字符,不得为空。说明 Skill 的用途及适用时机。 |
| 否 | 许可证名称,或附带许可证文件的引用。 |
| 否 | 最多 500 个字符。说明环境要求,如适用产品、系统软件包、网络访问等。 |
| 否 | 任意键值映射,用于补充元数据;键和值都必须是字符串。 |
| 否 | 以空格分隔的字符串,列出预先获准供 Skill 使用的工具。(实验性功能) |
最小示例:
SKILL.md--- name: skill-name description: 说明这个 Skill 的用途及适用时机。 ---包含可选字段的示例:
SKILL.md--- name: pdf-processing description: 提取 PDF 文本、填写表单、合并文件。处理 PDF 时使用。 license: Apache-2.0 metadata: author: example-org version: "1.0" ---
name 字段
必填的 name 字段:
- 长度必须为 1–64 个字符
- 只能包含 Unicode 小写字母、数字(
a-z、0-9)和连字符(-) - 不得以连字符(
-)开头或结尾 - 不得包含连续的连字符(
--) - 必须与父目录名称一致
有效示例:
name: pdf-processingname: data-analysisname: code-review无效示例:
name: PDF-Processing # 不允许大写字母name: -pdf # 不得以连字符开头name: pdf--processing # 不允许连续的连字符
description 字段
必填的 description 字段:
- 长度必须为 1–1,024 个字符
- 应同时说明 Skill 的用途及适用时机
- 应包含具体的关键词,帮助 Agent 识别相关任务
良好示例:
description: 从 PDF 文件中提取文本和表格、填写 PDF 表单,并合并多个 PDF。处理 PDF 文档,或用户提到 PDF、表单、文档提取时使用。欠佳示例:
description: 帮助处理 PDF。
license 字段
可选的 license 字段:
- 指定 Skill 采用的许可证
- 建议保持简短,填写许可证名称或附带许可证文件的名称即可
示例:
license: 专有许可证。完整条款见 LICENSE.txt
compatibility 字段
可选的 compatibility 字段:
- 如有填写,长度必须为 1–500 个字符
- 仅应在 Skill 有特定环境要求时填写
- 可以说明适用产品、所需系统软件包、网络访问要求等
示例:
compatibility: 适用于 Claude Code(或同类产品)compatibility: 需要 git、docker、jq,以及互联网访问权限compatibility: 需要 Python 3.14+ 和 uv
注意
大多数 Skill 不需要
compatibility字段。
metadata 字段
可选的 metadata 字段:
- 由字符串键映射到字符串值
- 客户端可以用它存储 Agent Skills 规范未定义的其他属性
- 建议为键选用不易重名的名称,避免意外冲突
示例:
metadata: author: example-org version: "1.0"
allowed-tools 字段
可选的 allowed-tools 字段:
- 以空格分隔的字符串,列出预先获准运行的工具
- 属于实验性功能,不同 Agent 实现对该字段的支持可能不同
示例:
allowed-tools: Bash(git:*) Bash(jq:*) Read
正文
前置元数据之后的 Markdown 正文用于编写 Skill 指令,没有格式限制。凡是有助于 Agent 有效完成任务的内容,都可以写入。
建议包含以下部分:
- 分步骤操作指令
- 输入与输出示例
- 常见边界情况
Agent 一旦决定激活某个 Skill,就会加载整个文件。如果 SKILL.md 内容较长,可以将部分内容拆分为引用文件。
可选目录
除了必需的 SKILL.md,Skill 目录还可以包含任意文件和目录。以下约定用于组织常见类型的内容,仅供参考。
scripts/
存放供 Agent 运行的可执行代码。脚本应当:
- 能够独立运行,或明确说明依赖
- 提供有助于排查问题的错误信息
- 妥善处理边界情况
支持哪些语言取决于 Agent 的具体实现,常见选择包括 Python、Bash 和 JavaScript。
references/
存放供 Agent 按需读取的补充文档:
REFERENCE.md——详细的技术参考FORMS.md——表单模板或结构化数据格式- 特定领域的文件,如
finance.md、legal.md
每份参考文件都应聚焦一个主题。Agent 会按需加载这些文件,因此文件越精简,上下文占用就越少。
assets/
存放静态资源:
- 模板(文档模板、配置模板)
- 图片(图示、示例)
- 数据文件(查找表、Schema)
渐进式披露
Agent 会逐步加载 Skill,仅在任务需要时读取更多细节。Skill 的结构应充分利用这一机制:
- 元数据(约 100 个 token):启动时加载所有 Skill 的
name和description字段 - 指令(建议少于 5,000 个 token):激活 Skill 时加载完整的
SKILL.md正文 - 资源(按需):仅在需要时加载文件,例如
scripts/、references/或assets/中的文件
主文件 SKILL.md 应少于 500 行。将详细的参考资料移到独立文件中。
文件引用
在 Skill 中引用其他文件时,使用相对于 Skill 根目录的路径:
SKILL.md
详见[参考指南](references/REFERENCE.md)。
运行提取脚本:
scripts/extract.py文件引用从 SKILL.md 出发只保留一层,避免层层嵌套的引用链。
校验
使用 skills-ref 参考库校验 Skill:
skills-ref validate ./my-skill该命令会检查 SKILL.md 的前置元数据是否有效,以及是否符合全部命名约定。