Skip to main content

​
目录结构

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

​
SKILL.md 格式

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

​
前置元数据

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

最小示例：
SKILL.md
---
name: 技能名称
description: 关于此技能做什么以及何时使用的描述。
---
包含可选字段的示例：
SKILL.md
---
name: pdf-processing
description: 提取 PDF 文本，填写表单，合并文件。处理 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: 专有。LICENSE.txt 包含完整条款

​
compatibility 字段

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

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

compatibility: 需要 git、docker、jq 以及互联网访问权限

compatibility: 需要 Python 3.14+ 和 uv
大多数技能不需要 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 个 token）：name 和 description 字段在启动时为所有技能加载
  2. 指令（建议 < 5000 个 token）：SKILL.md 正文在技能激活时加载
  3. 资源（按需）：文件（例如 scripts/、references/ 或 assets/ 中的文件）仅在需要时加载
将主 SKILL.md 保持在 500 行以下。将详细参考材料移至单独的文件。

​
文件引用

在技能中引用其他文件时，使用相对于技能根目录的路径：
SKILL.md
See [参考指南](references/REFERENCE.md) 以获取详情。

运行提取脚本：
scripts/extract.py
保持文件引用从 SKILL.md 起只有一层深度。避免深层嵌套的引用链。

​
验证

使用 skills-ref 参考库来验证您的技能： 
skills-ref validate ./my-skill
这将检查您的 SKILL.md 前置元数据是否有效并遵循所有命名约定。