SKILL.md 规范

SKILL.md 是 Skill 的入口文件，所有技能都至少需要一个 SKILL.md 文件。尽管 SKILL.md 本质上就是一份自然语言描述的操作手册，但为了能让 Agent 的理解和使用，我们在编写 SKILL.md 时，需要遵循基本的规范和结构。

SKILL.md 的基本结构

Frontmatter 元数据

Frontmatter 是 Markdown 文件开头的 YAML 块，用于定义文档的元数据。 通过三个短横线 --- 包裹起来，里面可以包含各种键值对信息。

Markdown 的 Frontmatter 定义了 Skill 的元数据，至少需要包含 name 和 description 两个字段。前者是技能的唯一标识，后者则是对技能功能的简要描述。

下面是一个 SKILL.md 的 Frontmatter 示例：

---
name: contract-review
description: "根据合同审核标准对合同进行审核，并生成审核报告。当用户需要审核合同时，可以使用此功能。"
---

name 规范

Skill 的 name 是它的唯一标识，必须遵循以下规范：

• 最多64个字符
• 仅限小写字母、数字和连字符
• 不得以连字符开头或结尾。

✅ 正确示例

• contract-review
• customer-support
• data-analysis

❌ 错误示例

• ContractReview （包含大写字母）
• contract_review （包含下划线）
• contract review （包含空格）
• -contract-review （以连字符开头）
• contract-review- （以连字符结尾）

description 规范

Skill 的 description 是对技能功能的简要描述，必须遵循以下规范：

• 最多 1024 个字符。
• 非空
• 描述技能的作用和使用时机

Agent 是通过 name 来识别和调用技能，而 description 则是帮助 Agent 理解技能功能和使用场景的关键。 因此，编写清晰、准确的 description 对于确保 Agent 能正确选择和使用技能至关重要。

✅ 正确示例

description: "根据合同审核标准对合同进行审核，并生成审核报告。当用户需要审核合同时使用此功能。"

❌ 错误示例

description: 处理 PDF 文件  # 过于简略，缺乏具体信息

其他可选的 Frontmatter 属性

除了 name 和 description，你还可以在 Frontmatter 中添加下面的属性来提供更多信息：

• license: 许可证名称或对许可证文件的引用
• compatibility: 兼容性信息，例如支持的 Agent 应用或依赖的运行环境¹。
• metadata: 其他自定义的元数据字段，可以根据需要添加, 比如技能的版本号、作者信息、更新日志等 。
• allowed-tools: 一组以空格分隔的、预先批准运行的工具，目前还处于实验阶段。例如 Bash(git:*) Bash(jq:*) Read。

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
allowed-tools: Bash(git:*) Bash(jq:*) Read
metadata:
  author: SkillPKG Team
  version: "1.0"
---

正文

Frontmatter 元数据之后的 Markdown 正文包含自然语言描写的技能指令。格式没有限制, 编写任何有助于Agent有效执行任务的内容即可。

尽管没有限制，一个合格的 Skill 正文通常包含以下内容：

• 执行步骤说明
• 输入和输出示例
• 常见边界情况

需要注意的一点： Agent 一旦决定使用某个技能，就会加载整个 SKILL.md 文件。为了避免上下文过长，建议将较长²的 SKILL.md 内容拆分为多个引用文件。 例如，你可以把技能的核心指令放在 SKILL.md 中，而把一些参考示例，模板文件放在 references 文件夹中的单独 Markdown 文件里，然后在 SKILL.md 中通过链接引用³它们。