目录结构

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

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档
├── assets/           # 可选：模板、资源
└── ...               # 任何其他文件或目录

SKILL.md 格式

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

Frontmatter

字段必需约束
name是最长 64 字符。仅允许小写字母、数字和连字符。
description是最长 1024 字符。描述 Skill 的功能和适用场景。
license否许可证名称或引用。
compatibility否最长 500 字符。环境要求。
metadata否任意键值映射。
allowed-tools否以空格分隔的预批准工具字符串。（实验性）

最小示例：

---
name: skill-name
description: 描述此 Skill 的功能和适用场景。
---

包含可选字段的示例：

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

name 字段

  • 必须为 1-64 个字符
  • 仅可包含小写字母（a-z）和连字符（-）
  • 不能以连字符开头或结尾
  • 不能包含连续连字符（--）
  • 必须与父目录名称匹配

description 字段

  • 必须为 1-1024 个字符
  • 应描述 Skill 的功能和适用场景
  • 应包含帮助 Agent 识别相关任务的关键词

compatibility 字段

仅在 Skill 有特定环境要求时才应包含：

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv

metadata 字段

从字符串键到字符串值的映射。建议使键名具有合理的唯一性以避免冲突。

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

allowed-tools 字段

以空格分隔的预批准工具字符串。实验性功能。

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

正文内容

frontmatter 之后的 Markdown 正文包含 Skill 指令。没有格式限制。

推荐包含：

  • 分步指令
  • 输入和输出示例
  • 常见边缘情况

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

可选目录

scripts/

可执行代码。脚本应该自包含或明确记录依赖项，包含有用的错误消息。

references/

附加文档，按需加载：

  • REFERENCE.md — 详细技术参考
  • FORMS.md — 表单模板
  • 领域特定文件（finance.md、legal.md 等）

assets/

静态资源：模板、图片、数据文件。

渐进式加载

Agent 渐进式加载 Skills：

  1. 元数据（约 100 token）— 启动时加载 name 和 description
  2. 指令（建议不超过 5,000 token）— 激活时加载完整 SKILL.md
  3. 资源（按需）— 仅在需要时加载文件

文件引用

使用从 Skill 根目录的相对路径，保持不超过一层深度。

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

验证

使用skills-ref参考库验证：

skills-ref validate ./my-skill