规范 - Agent Skills

本文档定义了 Agent Skills 格式。

目录结构

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

skill-name/
└── SKILL.md          # 必需

您可以选择性地包含附加目录如 scripts/、references/ 和 assets/ 来支持您的 skill。

SKILL.md 格式

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

Frontmatter（必需）

---
name: skill-name
description: 对此 skill 的功能及使用时机的描述。
---

包含可选字段：

---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

字段	必需	约束
`name`	是	最多 64 个字符。仅限小写字母、数字和连字符。不得以连字符开头或结尾。
`description`	是	最多 1024 个字符。非空。描述 skill 的功能及使用时机。
`license`	否	许可证名称或对捆绑许可证文件的引用。
`compatibility`	否	最多 500 个字符。指示环境要求（预期产品、系统包、网络访问等）。
`metadata`	否	用于附加元数据的任意键值映射。
`allowed-tools`	否	预批准的 skill 可使用的工具的空格分隔列表。（实验性）

`name` 字段

必需的 name 字段：

必须为 1-64 个字符
只能包含 unicode 小写字母数字字符和连字符（a-z 和 -）
不得以 - 开头或结尾
不得包含连续的连字符（--）
必须与父目录名称匹配

有效示例：

name: pdf-processing

name: data-analysis

name: code-review

无效示例：

name: PDF-Processing  # 不允许大写

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

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

`description` 字段

必需的 description 字段：

必须为 1-1024 个字符
应描述 skill 的功能及使用时机
应包含帮助 agents 识别相关任务的特定关键词

良好示例：

description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

较差示例：

description: 帮助处理 PDF。

`license` 字段

可选的 license 字段：

指定应用于 skill 的许可证
我们建议保持简短（许可证名称或捆绑许可证文件的名称）

示例：

license: 专有。LICENSE.txt 包含完整条款

`compatibility` 字段

可选的 compatibility 字段：

如果提供，必须为 1-500 个字符
仅应在您的 skill 有特定环境要求时包含
可以指示预期产品、必需的系统包、网络访问需求等

示例：

compatibility: 专为 Claude Code（或类似产品）设计

compatibility: 需要 git、docker、jq 和互联网访问

大多数 skills 不需要 compatibility 字段。

`metadata` 字段

可选的 metadata 字段：

从字符串键到字符串值的映射
客户端可以使用此字段存储 Agent Skills 规范未定义的附加属性
我们建议使您的键名具有合理的唯一性以避免意外冲突

示例：

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

`allowed-tools` 字段

可选的 allowed-tools 字段：

预批准可运行的工具的空格分隔列表
实验性。对此字段的支持可能因 agent 实现而异

示例：

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

主体内容

frontmatter 之后的 Markdown 主体包含 skill 指令。没有格式限制。编写任何有助于 agents 有效执行任务的内容。推荐的章节：

分步说明
输入和输出示例
常见边缘情况

请注意，一旦决定激活 skill，agent 将加载整个文件。考虑将较长的 SKILL.md 内容拆分到引用的文件中。

可选目录

scripts/

包含 agents 可以运行的可执行代码。脚本应：

自包含或清楚地记录依赖项
包含有用的错误消息
优雅地处理边缘情况

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

references/

包含 agents 在需要时可以阅读的附加文档：

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

保持单个参考文件专注。agents 按需加载这些文件，因此较小的文件意味着更少的上下文使用。

assets/

包含静态资源：

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

渐进式披露

skills 应结构化以高效使用上下文：

元数据（约 100 个 token）：所有 skills 的 name 和 description 字段在启动时加载
指令（建议 < 5000 个 token）：激活 skill 时加载完整的 SKILL.md 主体
资源（按需）：文件（例如 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 frontmatter 是否有效并遵循所有命名约定。

​目录结构

​SKILL.md 格式

​Frontmatter（必需）

​name 字段

​description 字段

​license 字段

​compatibility 字段

​metadata 字段

​allowed-tools 字段

​主体内容

​可选目录

​scripts/

​references/

​assets/

​渐进式披露

​文件引用

​验证

目录结构

SKILL.md 格式

Frontmatter（必需）

`name` 字段

`description` 字段

`license` 字段

`compatibility` 字段

`metadata` 字段

`allowed-tools` 字段

主体内容

可选目录

scripts/

references/

assets/

渐进式披露

文件引用

验证