Agent Skills 智能体技能格式规范
本文档定义了智能体技能的完整格式规范。
目录结构
一项智能体技能是一个至少包含SKILL.md文件的目录，基础结构如下：
skill-name/
└── SKILL.md # 必选文件💡你也可根据需求，选择性添加
scripts/、references/、assets/等附属目录，为技能提供配套支持。
SKILL.md 文件格式
SKILL.md文件的内容结构为YAML前置元数据在前，Markdown格式主体内容在后，二者依次排布。
前置元数据（必填）
基础必填格式：
---
name: skill-name
description: A description of what this skill does and when to use it.
---包含可选字段的完整示例：
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
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个
- 仅可包含Unicode小写字母、数字和连字符（
a-z、0-9、-） - 首尾不能是连字符，且不可出现连续的连字符（
--） - 字段值必须与技能的父目录名称完全一致
有效示例：
name: pdf-processingname: data-analysisname: 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 termscompatibility 字段
作为可选字段，compatibility字段需满足：若填写，字符长度为1-500个；仅当技能有特定运行环境要求时才需添加，可说明其适用的产品、所需的系统包、网络访问权限等。
示例：
compatibility: Designed for Claude Code (or similar products)compatibility: Requires git, docker, jq, and access to the internet注：绝大多数基础技能无需填写该字段。
metadata 字段
作为可选字段，metadata字段为字符串类型的键值对映射结构，可用于存储智能体技能规范中未定义的额外属性，方便客户端拓展使用。建议将键名设置为具有辨识度的唯一名称，避免出现命名冲突。
示例：
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/ 目录
用于存放技能运行所需的静态资源文件，常见类型包括：
- 各类模板（文档模板、配置模板等）
- 图片素材（流程图、示例图等）
- 数据文件（查找表、数据模式文件等）
渐进式信息披露
技能的内容结构需按照渐进式信息披露的原则设计，以实现语境资源的高效利用，具体规则为：
- 元数据（约100个令牌）：所有技能的
name和description字段，会在智能体启动时统一加载 - 操作指引（建议少于5000个令牌）：SKILL.md的完整主体内容，仅在技能被激活时加载
- 配套资源（按需加载）：
scripts/、references/、assets/等目录中的文件，仅在智能体执行任务需要时才加载
建议：将主文件SKILL.md的内容控制在500行以内，把详细的参考资料移至独立的外部文件中。
文件引用
在SKILL.md中引用技能包内的其他文件时，需使用以技能根目录为基准的相对路径，示例如下：
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文件的前置元数据是否有效，并验证所有命名是否符合本规范的约定。