规范

Agent Skills 的完整格式规范。

目录结构

一个 Skill 是一个目录，其中至少包含一个 SKILL.md 文件：

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

SKILL.md 格式

SKILL.md 文件必须包含 YAML 前缀，后跟 Markdown 内容。

Frontmatter

最小示例：

---
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 个字符

• 只能包含小写字母数字字符（a-z）和连字符（-）

• 不得以连字符（-）开头或结尾

• 不得包含连续连字符（--）

• 必须与父目录名称匹配

  有效示例：

name: pdf-processing

name: data-analysis

name: code-review

无效示例：

name: PDF-Processing  # 不允许大写

name: -pdf  # 不能以连字符开头

name: pdf--processing  # 不允许连续连字符

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 规范未定义的其他属性

• 我们建议使您的键名具有合理的唯一性，以避免意外冲突

  示例：

`yaml theme={null}
metadata:
author: example-org
version: “1.0”

#### `allowed-tools` 字段

可选的 `allowed-tools` 字段：

* 预先批准运行的、以空格分隔的工具字符串
* 实验性。此字段的支持可能因代理实现而异

**示例：**

```yaml theme={null}
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/

包含静态资源：

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

渐进式披露

代理逐步加载技能，仅在任务需要时才拉取更多细节。技能的构建应充分利用这一点：

1. 元数据（约 100 个 token）：所有技能的 name 和 description 字段在启动时加载
2. 说明（建议 < 5000 个 token）：技能激活时加载完整的 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 是否有效，并遵循所有命名约定。