技能规格(Specification)定义

技能的完整格式规范，本文档描述技能的定义格式。

一、目录结构

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

skill-name/
└── SKILL.md          # Required

二、SKILL.md 格式

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

2.1 前置格式（必填）

---
name: skill-name
description: A description of what this skill does and when to use it.
---

包含可选参数：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

​1. 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

2. description参数

必填description参数：

• 必须为 1-1024 个字符

• 应该描述该技能的作用以及何时使用。

• 应包含有助于代理识别相关任务的特定关键词。

正面例子：

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.

​

3. license参数

可选license参数：

• 指明适用于该技能的许可证

• 我们建议尽量简短（可以是许可证名称，也可以是捆绑许可证文件的名称）。

例子：

license: Proprietary. LICENSE.txt has complete terms

​4.compatibility参数

compatibility参数可选compatibility参数：

• 如果提供，则必须为 1-500 个字符。

• 只有当你的技能有特定的环境要求时，才应将其包含在内。

• 可以说明目标产品、所需系统软件包、网络接入需求等。

例如：

compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet

5. metadata参数

可选metadata参数：

• 从字符串键到字符串值的映射

• 客户可以使用此功能存储代理技能规范中未定义的其他属性。

• 我们建议您使用尽可能独特的密钥名称，以避免意外冲突。

例子：

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

​6. allowed-tools 参数

allowed-tools参数可选allowed-tools参数：

• 以空格分隔的已预先批准运行的工具列表

• 实验性功能。不同代理实现对该参数的支持可能有所不同。

例子：

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

2.2 Body内容

前置元数据之后的 Markdown 正文包含技能说明。格式没有限制。只需编写有助于代理人有效完成任务的内容即可。推荐内容：

• 分步说明

• 输入和输出示例

• 常见边界情况

请注意，代理程序会在决定激活技能时加载整个文件。建议将较长的SKILL.md内容拆分成多个引用文件。

三、可选目录

scripts/

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

• 要么是自包含的，要么清楚地记录依赖关系

• 包含有用的错误信息

• 优雅地处理极端情况

支持的语言取决于代理的具体实现。常见的语言包括 Python、Bash 和 JavaScript。

references/

包含代理需要时可查阅的其他文档：

• REFERENCE.md- 详细技术参考

• FORMS.md- 表单模板或结构化数据格式

• 域特定文件（finance.md，，legal.md等）

保持各个参考文件的简洁性。代理程序按需加载这些文件，因此文件越小，对上下文信息的依赖就越少。

assets/

包含静态资源：

• 模板（文档模板、配置模板）

• 图片（图表、示例）

• 数据文件（查找表、模式）

四、渐进式披露

技能应结构化，以便有效利用上下文：

1. 元数据（约 100 个tokens）：所有技能的 name、description字段在启动时加载。

2. 说明（建议使用少于 5000 个tokens）：SKILL.md技能激活时，全部都会加载完毕。

3. 资源（按需加载）：文件（例如位于 scripts/、references/ 或 assets/）仅在需要时加载。

正文请控制SKILL.md在 500 行以内。详细的参考资料请移至单独的文件中。

五、文件引用

在技​​能中引用其他文件时，请使用相对于技能根目录的相对路径：

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

Run the extraction script:
scripts/extract.py

六、验证

使用skills-ref参考库来验证您的技能：

skills-ref validate ./my-skill

这会检查您的SKILL.mdfrontmatter 是否有效并符合所有命名规则。