Skip to main content

​
目录结构

一个 skill 至少是一个包含 SKILL.md 文件的目录： 
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

​
SKILL.md 格式

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

​
Frontmatter

字段必填约束
name是最长 64 个字符。只能包含小写字母、数字和连字符。不能以连字符开头或结尾。
description是最长 1024 个字符。不能为空。用于描述这个 skill 做什么，以及什么时候使用它。
license否许可证名称，或对随 skill 一起打包的许可证文件的引用。
compatibility否最长 500 个字符。用于说明环境要求（目标产品、系统包、网络访问等）。
metadata否用于附加元数据的任意键值映射。
allowed-tools否以空格分隔的预批准工具列表，表示这个 skill 可以使用哪些工具。（实验性）

最小示例：
SKILL.md
---
name: skill-name
description: A description of what this skill does and when to use it.
---
包含可选字段的示例：
SKILL.md
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
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  # uppercase not allowed

name: -pdf  # cannot start with hyphen

name: pdf--processing  # consecutive hyphens not allowed

​
description 字段

必填的 description 字段：
  • 必须为 1 到 1024 个字符
  • 应同时说明这个 skill 做什么，以及什么时候使用它
  • 应包含有助于 agent 识别相关任务的具体关键词

良好示例：
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 字段：
  • 用于声明这个 skill 适用的许可证
  • 建议保持简短（许可证名称，或随 skill 一起打包的许可证文件名即可）

示例：
license: Proprietary. LICENSE.txt has complete terms

​
compatibility 字段

可选的 compatibility 字段：
  • 如果提供，长度必须为 1 到 500 个字符
  • 只有当你的 skill 存在明确环境要求时才应填写
  • 可用于说明目标产品、所需系统包、网络访问需求等

示例：
compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet
大多数 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 的实际说明。正文没有固定格式限制，只要能帮助 agent 有效完成任务即可。 推荐包含的部分：
  • 分步骤说明
  • 输入与输出示例
  • 常见边界情况
请注意，一旦 agent 决定激活某个 skill，它会加载整个文件。因此对于较长的 SKILL.md，应考虑把内容拆分到被引用的文件中。

​
可选目录

​
scripts/

包含 agent 可执行的代码。脚本应当：
  • 尽量自包含，或者清晰说明依赖项
  • 提供有帮助的错误信息
  • 对边界情况做出稳妥处理
支持哪些语言取决于 agent 的具体实现。常见选择包括 Python、Bash 和 JavaScript。

​
references/

包含 agent 在需要时可以读取的附加文档：
  • REFERENCE.md - Detailed technical reference
  • FORMS.md - Form templates or structured data formats
  • Domain-specific files (finance.md, legal.md, etc.)
尽量让单个引用文件保持聚焦。agent 是按需加载这些文件的，因此文件越小，占用的上下文通常越少。

​
assets/

包含静态资源：
  • 模板（文档模板、配置模板）
  • 图片（图示、示例）
  • 数据文件（查找表、schema）

​
渐进式披露

skills 应当围绕“高效使用上下文”来组织：
  1. 元数据（约 100 tokens）：启动时会为所有 skills 加载 name 和 description 字段
  2. 说明（建议少于 5000 tokens）：skill 被激活时会加载完整的 SKILL.md 正文
  3. 资源（按需加载）：只有在确实需要时，才会加载 scripts/、references/ 或 assets/ 等目录中的文件
建议将主 SKILL.md 控制在 500 行以内。更详细的参考材料应拆到独立文件中。

​
文件引用

当在 skill 中引用其他文件时，应使用相对于 skill 根目录的路径：
SKILL.md
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py
文件引用最好保持在相对 SKILL.md 的一层深度内，避免形成过深的引用链。

​
校验

使用 skills-ref 参考库来校验你的 skills： 
skills-ref validate ./my-skill
它会检查你的 SKILL.md frontmatter 是否有效，并确认是否遵循了所有命名约定。