格式规范#

Agent Skills 的完整格式规范。

目录结构#

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

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

SKILL.md 格式#

SKILL.md 文件必须包含 YAML 前置参数（Frontmatter），随后是 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 个字符
• 仅包含 Unicode 小写字母数字字符 (a-z) 和连字符 (-)
• 不能以连字符 (-) 开头或结尾
• 不能包含连续的连字符 (--)
• 必须与父目录名称一致

有效示例： pdf-processing, data-analysis, code-review

无效示例： PDF-Processing (包含大写), -pdf (连字符开头), pdf--processing (连续连字符)

description 字段#

必需的 description 字段要求：

• 长度为 1-1024 个字符
• 应同时描述 Skill 的功能和使用时机
• 应包含有助于智能体 (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 字段：

• 指定应用于该 Skill 的许可证
• 建议简短（许可证名称或许可证文件名）

示例：

license: Proprietary. LICENSE.txt has complete terms

compatibility 字段#

可选的 compatibility 字段：

• 如果提供，长度为 1-500 个字符
• 仅在 Skill 有特定环境要求时包含
• 可以指示目标产品、所需的系统包、网络访问需求等

示例：

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:
  author: example-org
  version: "1.0"

allowed-tools 字段#

可选的 allowed-tools 字段：

• 预先批准运行的工具列表，以空格分隔
• 实验性功能。支持情况取决于智能体的具体实现。

示例：

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

主体内容#

Frontmatter 之后的 Markdown 正文包含 Skill 的指令。没有格式限制。可以编写任何有助于智能体高效执行任务的内容。

建议包含的部分：

• 分步操作指南
• 输入和输出示例
• 常见边缘情况

请注意，一旦智能体决定启用某个 Skill，它将加载整个文件。建议将较长的 SKILL.md 内容拆分到引用的文件中。

可选目录#

scripts/#

包含智能体可以运行的可执行代码。脚本应：

• 自包含或明确说明依赖项
• 包含有用的错误提示
• 优雅地处理边缘情况

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

references/#

包含智能体在需要时可以阅读的补充文档：

• REFERENCE.md - 详细的技术参考
• FORMS.md - 表单模板或结构化数据格式
• 特定领域的文档（如 finance.md, legal.md 等）

保持每个 参考文件 的专注度。智能体按需加载这些文件，较小的文件意味着更少的上下文消耗。

assets/#

包含静态资源：

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

渐进式加载 (Progressive disclosure)#

Skills 的结构应设计为高效利用上下文：

1. 元数据 (~100 tokens)：name 和 description 字段在启动时为所有 Skill 加载。
2. 指令 (建议 < 5000 tokens)：当 Skill 被激活时，加载完整的 SKILL.md 主体。
3. 资源 (按需)：仅在需要时加载文件（例如 scripts/, references/ 或 assets/ 中的文件）。

保持 SKILL.md 主体在 500 行以内。将详细的参考资料移至独立文件。

文件引用#

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

详情请参阅 [参考指南](references/REFERENCE.md)。

运行提取脚本：
scripts/extract.py

建议保持文件引用距离 SKILL.md 仅一级深度。避免深层嵌套的引用链。

校验#

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

skills-ref validate ./my-skill

这将检查你的 SKILL.md 前置参数是否有效，并遵循所有命名规范。