Agent Skills

格式规范

Agent Skills 的完整格式规范。

目录结构

Skill 是一个目录,至少包含一个 SKILL.md 文件:

skill-name/
├── SKILL.md          # 必需:元数据与指令
├── scripts/          # 可选:可执行代码
├── references/       # 可选:文档
├── assets/           # 可选:模板、资源
└── ...               # 其他任意文件或目录

SKILL.md 格式

SKILL.md 文件必须以前置元数据(YAML frontmatter)开头,后接 Markdown 正文。

前置元数据

字段

是否必需

约束

name

是

最多 64 个字符。仅限小写字母、数字和连字符,不得以连字符开头或结尾。

description

是

最多 1,024 个字符,不得为空。说明 Skill 的用途及适用时机。

license

否

许可证名称,或附带许可证文件的引用。

compatibility

否

最多 500 个字符。说明环境要求,如适用产品、系统软件包、网络访问等。

metadata

否

任意键值映射,用于补充元数据;键和值都必须是字符串。

allowed-tools

否

以空格分隔的字符串,列出预先获准供 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-processing
name: data-analysis
name: 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 的结构应充分利用这一机制:

  1. 元数据(约 100 个 token):启动时加载所有 Skill 的 name 和 description 字段
  2. 指令(建议少于 5,000 个 token):激活 Skill 时加载完整的 SKILL.md 正文
  3. 资源(按需):仅在需要时加载文件,例如 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 的前置元数据是否有效,以及是否符合全部命名约定。