SKILL.md 格式规范

Agent Skills 的完整格式规范——目录结构、YAML Frontmatter 字段、文件引用与验证。

目录结构

一个标准的 Skill 是一个包含 SKILL.md 文件的文件夹：

必需文件

SKILL.md — 定义 Skill 的核心文件，包含 YAML Frontmatter 和 Markdown 指令体

可选目录

目录	用途
`scripts/`	Agent 可以运行的可执行代码（Bash、Python、JavaScript 等）
`references/`	按需加载的附加文档（技术参考、API 文档、表单模板等）
`assets/`	静态资源（文档模板、配置模板、图片、数据文件等）

SKILL.md 文件格式

SKILL.md 必须包含 YAML Frontmatter 后跟 Markdown 内容体。

最小示例

markdown

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))

Replace <sides> with the number of sides on the die (e.g., 6 for a standard die, 20 for a d20).


### 完整示例

```markdown
---
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"
---

## Extract PDF text

Use pdfplumber for text extraction. For scanned documents, fall back to pdf2image with pytesseract.

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Merge PDFs

Use PyPDF2 to merge multiple PDF files:

python

from PyPDF2 import PdfMerger

merger = PdfMerger()
for pdf in pdf_files:
    merger.append(pdf)
merger.write("merged.pdf")
merger.close()


## Frontmatter 字段详解

### `name` （必填）

Skill 的标识符，必须与父文件夹名称一致。

| 约束 | 说明 |
|------|------|
| 长度 | 1-64 字符 |
| 字符集 | 仅允许小写字母、数字和连字符 |
| 开头/结尾 | 不能以连字符开头或结尾 |
| 连续性 | 不允许连续连字符 (`--`) |

**有效示例**：`pdf-processing`、`data-analysis`、`code-review`

**无效示例**：`PDF-Processing` (大写)、`-pdf` (以连字符开头)、`pdf--processing` (连续连字符)

### `description` （必填）

描述 Skill 的作用和使用场景。这是 Agent 判断是否激活该 Skill 的关键依据。

| 约束 | 说明 |
|------|------|
| 长度 | 1-1024 字符 |
| 内容 | 必须非空，应同时描述"做什么"和"何时使用" |
| 关键词 | 应包含帮助 Agent 识别相关任务的具体关键词 |

**好的示例**：
```yaml
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.

差的示例：

yaml

description: Helps with PDFs.

`license` （可选）

指定 Skill 的许可证。建议保持简洁（许可证名称或捆绑的许可证文件名）。

yaml

license: Apache-2.0

yaml

license: Proprietary. LICENSE.txt has complete terms

`compatibility` （可选）

指示运行环境要求（目标产品、系统软件包、网络访问等）。大多数 Skill 无需此字段。

yaml

compatibility: Designed for Claude Code (or similar products)

yaml

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

yaml

compatibility: Requires Python 3.14+ and uv

`metadata` （可选）

任意键值映射，用于存储额外元数据。建议使用足够唯一的键名避免冲突。

yaml

metadata:
  author: example-org
  version: "1.0"
  category: data-processing

`allowed-tools` （可选，实验性）

空格分隔的工具列表，指定该 Skill 可以使用的预批准工具。各平台支持程度可能不同。

yaml

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

`disable-model-invocation` （可选）

当设为 true 时，该 Skill 仅在通过 /skill-name 显式调用时才会被使用。Agent 不会基于上下文自动调用它。这让 Skill 行为类似传统的斜杠命令（slash command）。

yaml

disable-model-invocation: true

指令体内容

Frontmatter 之后的 Markdown 体包含完整的指令。没有严格的格式限制，建议包含以下内容：

逐步指令 — 清晰的步骤化流程
输入/输出示例 — 具体的例子帮助 Agent 理解预期
常见边界情况 — 非显而易见的问题和处理方式
Gotchas 部分 — 环境特定的事实，违背常理的假设

文件引用

在 Skill 内部引用其他文件时，使用相对于 Skill 根目录的路径：

markdown

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

Run the extraction script:
scripts/extract.py

建议将文件引用保持在 SKILL.md 一层深度，避免深度嵌套的引用链。

渐进式披露

Agent Skills 的核心设计原则是渐进式披露，让 Agent 按需加载更多细节：

阶段	加载内容	Token 估算	时机
发现	`name` + `description`	~100	Agent 启动时
激活	完整 `SKILL.md` 体	< 5000 推荐	任务匹配时
执行	`scripts/`、`references/`、`assets/`	按需	执行过程中

建议：将 SKILL.md 保持在 500 行以内，详细参考材料移至单独文件。

验证

使用 skills-ref 参考库验证 Skill 格式：

bash

skills-ref validate ./my-skill

这会检查 SKILL.md 的 Frontmatter 是否有效以及是否遵循所有命名约束。

平台特定扩展

Cursor 特定字段

Cursor 在标准之外支持以下字段：

字段	说明
`disable-model-invocation`	当为 `true` 时，仅通过 `/skill-name` 显式调用

OpenAI Codex 特定字段

OpenAI Codex 支持标准规范中的所有字段，并在 codex/skills/ 目录中自动发现 Skills。

Claude 特定字段

Claude.ai 和 Claude Code 在 .claude/skills/ 目录中自动发现 Skills，支持标准规范中的所有字段。

完整字段汇总

字段	必填	类型	约束	说明
`name`	是	string	1-64 字符，小写字母/数字/连字符	Skill 标识符，必须与文件夹名称一致
`description`	是	string	1-1024 字符	描述作用和使用场景
`license`	否	string	—	许可证名称或文件引用
`compatibility`	否	string	1-500 字符	运行环境要求
`metadata`	否	map	—	额外元数据键值对
`allowed-tools`	否	string	—	空格分隔的预批准工具列表（实验性）
`disable-model-invocation`	否	boolean	—	禁用自动调用，仅显式调用

SKILL.md 格式规范 ​

目录结构 ​

必需文件 ​

可选目录 ​

SKILL.md 文件格式 ​

最小示例 ​

Merge PDFs ​

license （可选） ​

compatibility （可选） ​

metadata （可选） ​

allowed-tools （可选，实验性） ​

disable-model-invocation （可选） ​

指令体内容 ​

文件引用 ​

渐进式披露 ​

验证 ​

平台特定扩展 ​

Cursor 特定字段 ​

OpenAI Codex 特定字段 ​

Claude 特定字段 ​

完整字段汇总 ​

延伸阅读 ​

SKILL.md 格式规范

目录结构

必需文件

可选目录

SKILL.md 文件格式

最小示例

Merge PDFs

`license` （可选）

`compatibility` （可选）

`metadata` （可选）

`allowed-tools` （可选，实验性）

`disable-model-invocation` （可选）

指令体内容

文件引用

渐进式披露

验证

平台特定扩展

Cursor 特定字段

OpenAI Codex 特定字段

Claude 特定字段

完整字段汇总

延伸阅读