规范

Note

Agent Skills 的完整格式规范。

本文档定义了 Agent Skills 的格式。

目录结构

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

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

您可以可选地包含 附加目录，例如 scripts/、references/ 和 assets/ 来支持您的技能。

SKILL.md 格式

SKILL.md 文件必须包含 YAML 前置元数据，后跟 Markdown 内容。

前置元数据（必需）

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

包含可选字段：

---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
字段必需约束
name是最多 64 个字符。仅允许小写字母、数字和连字符。不能以连字符开头或结尾。
description是最多 1024 个字符。非空。描述技能的功能和使用时机。
license否许可证名称或对捆绑许可证文件的引用。
compatibility否最多 500 个字符。指示环境要求（目标产品、系统包、网络访问等）。
metadata否用于附加元数据的任意键值映射。
allowed-tools否技能可以使用的事先批准工具的以空格分隔的列表。（实验性）

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: 从 PDF 文件中提取文本和表格，填写 PDF 表单，并合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

不佳示例：

description: 帮助处理 PDF。

license 字段

可选的 license 字段：

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

示例：

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

compatibility 字段

可选的 compatibility 字段：

  • 如果提供，必须是 1-500 个字符
  • 仅当您的技能有特定环境要求时才应包含
  • 可以指示目标产品、所需的系统包、网络访问需求等

示例：

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

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

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

metadata 字段

可选的 metadata 字段：

  • 从字符串键到字符串值的映射
  • 客户端可以使用它来存储 Agent Skills 规范未定义的附加属性
  • 我们建议使键名合理独特，以避免意外冲突

示例：

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

allowed-tools 字段

可选的 allowed-tools 字段：

  • 事先批准可以运行的工具的以空格分隔的列表
  • 实验性。对此字段的支持可能因智能体实现而异

示例：

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

正文内容

前置元数据后的 Markdown 正文包含技能说明。没有格式限制。写任何有助于智能体有效执行任务的内容。

推荐章节：

  • 分步说明
  • 输入和输出示例
  • 常见的边界情况

请注意，智能体一旦决定激活技能就会加载整个文件。考虑将较长的 SKILL.md 内容拆分为引用的文件。

可选目录

scripts/

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

  • 自包含或明确记录依赖项
  • 包含有用的错误消息
  • 妥善处理边界情况

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

references/

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

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

保持单个 引用文件 的重点。智能体按需加载这些文件，因此较小的文件意味着较少的上下文使用。

assets/

包含静态资源：

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

渐进式披露

技能应该为高效使用上下文而进行结构化：

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

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

文件引用

引用技能中的其他文件时，使用从技能根目录开始的相对路径：

有关详细信息，请参阅 [参考指南](references/REFERENCE.md)。

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

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

验证

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

skills-ref validate ./my-skill

这将检查您的 SKILL.md 前置元数据是否有效并遵循所有命名约定。