规范

Agent Skills 的完整格式规范。

目录结构

技能至少是一个包含 SKILL.md 文件的目录： SKILL.md

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

SKILL.md 格式

SKILL.md 文件必须包含 YAML frontmatter，后接 Markdown 正文。 SKILL.md

前置元数据

字段	必填	约束
`name`	是	最多 64 个字符。仅允许小写字母、数字和连字符。不能以连字符开头或结尾。
`description`	是	最多 1024 个字符。不能为空。说明技能做什么以及何时使用。
`license`	否	许可证名称或打包的许可证文件引用。
`compatibility`	否	最多 500 个字符。说明环境要求（目标产品、系统包、网络访问等）。
`metadata`	否	用于附加元数据的任意键值映射。
`allowed-tools`	否	由空格分隔的预批准工具字符串，技能可使用这些工具。（实验性）

最小示例：

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

包含可选字段的示例：

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

name 字段

必填的 name 字段： name

必须为 1-64 个字符
仅可包含 Unicode 小写字母数字字符（a-z、0-9）和连字符（-） (a-z, 0-9, -)
不能以连字符（-）开头或结尾
不能包含连续连字符（--）
必须与父目录名称一致

有效示例：

name: pdf-processing

name: data-analysis

name: code-review

无效示例：

name: PDF-Processing  # uppercase not allowed

name: -pdf  # cannot start with hyphen

name: pdf--processing  # consecutive hyphens not allowed

description 字段

必填的 description 字段： description

必须为 1-1024 个字符
应同时说明技能做什么以及何时使用
应包含帮助 Agent 识别相关任务的具体关键词

好示例：

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 字段

可选的 license 字段： license

指定适用于该技能的许可证
建议保持简短（可以是许可证名称，或打包许可证文件的名称）

示例：

license: Proprietary. LICENSE.txt has complete terms

compatibility 字段

可选的 compatibility 字段： compatibility

如提供，必须为 1-500 个字符
仅当技能有特定环境要求时才应包含
可指明目标产品、所需系统包、网络访问需求等。

示例：

compatibility: Designed for Claude Code (or similar products)

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

compatibility: Requires Python 3.14+ and uv

metadata 字段

可选的 metadata 字段： metadata

从字符串键到字符串值的映射
客户端可使用它来存储 Agent Skills 规范未定义的附加属性
建议让键名足够独特，以避免意外冲突

示例：

metadata:
  author: example-org
  version: "1.0"

allowed-tools 字段

可选的 allowed-tools 字段： allowed-tools

以空格分隔、预先批准可运行的工具字符串
实验性。不同 Agent 实现对该字段的支持可能不同

示例：

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

正文内容

frontmatter 后面的 Markdown 正文包含技能指令。这里没有格式限制，写下任何能帮助 Agent 高效完成任务的内容即可。

推荐章节：

逐步说明
输入和输出示例
常见边界情况

请注意，Agent 一旦决定激活技能，就会加载整个文件。较长的 SKILL.md 内容可以拆分到引用文件中。 SKILL.md

可选目录

scripts/

包含可由 Agent 运行的可执行代码。脚本应当：

保持自包含，或清楚说明依赖
包含有帮助的错误信息
优雅处理边界情况

支持的语言取决于 Agent 实现。常见选项包括 Python、Bash 和 JavaScript。

references/

包含可供 Agent 在需要时读取的附加文档：

REFERENCE.md - 详细技术参考
FORMS.md - 表单模板或结构化数据格式
领域专用文件 (finance.md, legal.md, etc.)

保持单个参考文件聚焦。Agent 会按需加载这些文件，因此更小的文件意味着更少的上下文占用。

assets/

包含静态资源：

模板（文档模板、配置模板）
图片（图示、示例）
数据文件（查找表、模式）

渐进式披露

Agent 会渐进式加载技能，只在任务需要时才拉取更多细节。技能应按此方式组织：

元数据 (~100 tokens): 启动时会为所有技能加载 name 和 description 字段 name description
指令 (< 5000 tokens recommended): 技能激活时会加载完整的 SKILL.md 正文 SKILL.md
资源 (as needed): 文件（例如 scripts/、references/ 或 assets/ 中的文件）只在需要时加载 scripts/ references/ assets/

将主 SKILL.md 控制在 500 行以内。把详细参考资料移到单独文件中。 SKILL.md

文件引用

在技能中引用其他文件时，请使用相对于技能根目录的路径：

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

Run the extraction script:
scripts/extract.py

文件引用保持在 SKILL.md 下一级。避免过深的引用链。 SKILL.md

校验

使用 skills-ref 参考库来校验你的技能：

skills-ref validate ./my-skill

这会检查你的 SKILL.md frontmatter 是否有效，并且是否遵循所有命名规范。 SKILL.md