Agent Skills 规范说明

---

title: "Agent Skills 规范说明"

description: "Agent Skills 的完整格式规范。"

目录结构

一个技能是一个目录，至少包含一个 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 内容。

Frontmatter

Frontmatter 是内容文件的头部元数据，是整个内容系统的数据基础。

你可以在 Markdown 文件的顶部添加 front matter。它是一个使用 YAML 格式定义元数据的块，位于文件顶部的三个连字符 --- 之间。

字段	必需	约束
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 字段：

• 必须为 1-64 个字符
• 仅可包含 Unicode 小写字母数字字符（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 字段：

• 必须为 1-1024 个字符
• 应同时描述技能的用途以及使用时机
• 应包含有助于智能体识别相关任务的具体关键词

良好示例：

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: Proprietary. LICENSE.txt has complete terms

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

大多数技能不需要 compatibility 字段。

metadata 字段

可选的 metadata 字段：

• 一个从字符串键到字符串值的映射
• 客户端可借此存储 Agent Skills 规范未定义的额外属性
• 我们建议让键名具备一定的唯一性，以避免意外的冲突

示例：

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

allowed-tools 字段

可选的 allowed-tools 字段：

• 以空格分隔的字符串，列出预先批准可运行的工具
• 实验性。不同智能体实现对该字段的支持可能有所不同

示例：

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

正文内容

frontmatter 之后的 Markdown 正文包含技能指令。格式上没有任何限制，可以写入任何有助于智能体有效完成任务的内容。

推荐章节：

• 分步指令
• 输入与输出示例
• 常见边界情况

请注意，一旦智能体决定激活某个技能，就会加载该文件的全部内容。对于较长的 SKILL.md，建议将部分内容拆分到被引用的文件中。

可选目录

scripts/

存放智能体可执行的可运行代码。脚本应：

• 自包含，或清晰地记录其依赖
• 包含有用的错误提示
• 妥善处理边界情况

所支持的语言取决于智能体实现。常见选择包括 Python、Bash 和 JavaScript。

references/

存放智能体可按需阅读的补充文档：

• REFERENCE.md - 详细的技术参考
• FORMS.md - 表单模板或结构化数据格式
• 领域相关文件（finance.md、legal.md 等）

保持各个参考文件聚焦。智能体按需加载这些文件，因此文件越小，上下文消耗越少。

assets/

存放静态资源：

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

渐进性披露

智能体渐进性地加载技能，仅在任务需要时才拉取更多细节。技能的结构应充分利用这一点：

1. 元数据 （约 100 tokens）：所有技能的 name 与 description 字段在启动时加载
2. 指令 （建议 < 5000 tokens）：技能被激活时加载完整的 SKILL.md 正文
3. 资源 （按需）：文件（例如 scripts/、references/ 或 assets/ 中的文件）仅在需要时加载

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

文件引用

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

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

Run the extraction script:
scripts/extract.py

文件引用请保持在距 SKILL.md 一层以内。避免过深的嵌套引用链。

验证

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

skills-ref validate ./my-skill

它会检查你的 SKILL.md frontmatter 是否有效，并遵循所有命名约定。