一、目录结构

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

二、SKILL.md 格式

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

1. 前置元数据（必需）

--- name: skill-name description: 对这个技能的作用和使用场景的描述。 ---

可选字段：

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

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 个字符应描述技能的作用和使用场景应包含有助于智能体识别相关任务的特定关键词

好的示例：

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

差的示例：

description: 帮助处理 PDF。

license 字段

可选的 license 字段：

指定应用于该技能的许可证

建议保持简短（许可证名称或捆绑许可证文件的名称）

示例：

license: Proprietary. LICENSE.txt 包含完整条款

compatibility 字段

可选的 compatibility 字段：

如果提供，长度为 1-500 个字符仅当技能有特定的环境要求时才包含可以表明目标产品、所需的系统包、网络访问需求等

示例：

compatibility: 为 Claude Code（或类似产品）设计 compatibility: 需要 git、docker、jq，并且需要访问互联网

metadata 字段

可选的 metadata 字段：

从字符串键到字符串值的映射客户端可以使用它来存储未在智能体技能规范中定义的额外属性建议使你的键名具有一定的唯一性，以避免意外冲突

示例：

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

allowed-tools 字段

可选的 allowed-tools 字段：

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

示例：

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

2. 正文内容（Body Content）

前置元数据之后的 Markdown 正文包含技能的指令。没有格式限制。写任何有助于智能体有效完成任务的内容。

推荐的章节：

步骤说明（step-by-step instructions）输入和输出的示例常见的边缘情况

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

三、可选目录

1. scripts/

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

是自包含的，或者清晰地记录依赖关系包含有用的错误消息优雅地处理边缘情况

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

2. references/

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

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

保持单独的 参考文件（reference files）聚焦。智能体会按需加载这些文件，因此较小的文件意味着较少的上下文使用。

3. assets/

包含静态资源：

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

四、渐进式披露（Progressive Disclosure）

技能应该结构化，以便高效使用上下文：

元数据（约 100 个token）：在启动时加载所有技能的 name 和 description 字段指令（建议少于 5000 个token）：激活技能时加载完整的 SKILL.md 正文资源（按需）：文件（例如 scripts/、references/ 或 assets/ 中的文件）仅在需要时加载

保持你的主 SKILL.md 不超过 500 行。将详细的参考材料移到单独的文件中。

五、文件引用

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

保持文件引用从 SKILL.md 开始只有一层深。避免深度嵌套的引用链。

六、验证

使用 skills-ref 参考库来验证你的技能。skills-ref 是官方提供的用于验证技能（Skill）合法性的工具。

可以直接使用 npx 运行 skills-ref 工具来验证一个技能目录：

npx skills-ref validate .agents/skills/hello-world

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

也可以先进行安装，然后再验证。根据你的编程环境，有两种安装方式：

安装成功后，可以使用以下核心命令。

（1）验证技能

这是最常用的命令，用于检查你的 SKILL.md 文件格式是否正确：

skills-ref validate ./你的技能目录

例如，skills-ref validate ./my-skill

如果验证通过，会显示成功信息；如果失败，会指出具体错误（如缺少必填字段、name 格式错误等）。

（2）读取技能属性

以 JSON 格式输出技能的元数据（如 name、description 等）：

skills-ref read-properties ./my-skill

这个命令可以帮助你快速检查技能的前置元数据是否正确解析 。

例如，

npx skills-ref read-properties .agents/skills/hello-world { "name": "hello-world", "description": "A simple skill that shoud be used to respond to a user when the enter the phrase \"hello world\"." }