> ## Documentation Index
> Fetch the complete documentation index at: https://skills.developerdoc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 规范

> Agent Skills 的完整格式规范。

## 目录结构

一个 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 可以使用哪些工具。（实验性）      |

<Card>
  **最小示例：**

  ```markdown SKILL.md theme={null}
  ---
  name: skill-name
  description: A description of what this skill does and when to use it.
  ---
  ```

  **包含可选字段的示例：**

  ```markdown SKILL.md theme={null}
  ---
  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"
  ---
  ```
</Card>

#### `name` 字段

必填的 `name` 字段：

* 必须为 1 到 64 个字符
* 只能包含 unicode 小写字母数字字符（`a-z`）和连字符（`-`）
* 不能以连字符（`-`）开头或结尾
* 不能包含连续连字符（`--`）
* 必须与父目录名称一致

<Card>
  **有效示例：**

  ```yaml theme={null}
  name: pdf-processing
  ```

  ```yaml theme={null}
  name: data-analysis
  ```

  ```yaml theme={null}
  name: code-review
  ```

  **无效示例：**

  ```yaml theme={null}
  name: PDF-Processing  # uppercase not allowed
  ```

  ```yaml theme={null}
  name: -pdf  # cannot start with hyphen
  ```

  ```yaml theme={null}
  name: pdf--processing  # consecutive hyphens not allowed
  ```
</Card>

#### `description` 字段

必填的 `description` 字段：

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

<Card>
  **良好示例：**

  ```yaml theme={null}
  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.
  ```

  **较差示例：**

  ```yaml theme={null}
  description: Helps with PDFs.
  ```
</Card>

#### `license` 字段

可选的 `license` 字段：

* 用于声明这个 skill 适用的许可证
* 建议保持简短（许可证名称，或随 skill 一起打包的许可证文件名即可）

<Card>
  **示例：**

  ```yaml theme={null}
  license: Proprietary. LICENSE.txt has complete terms
  ```
</Card>

#### `compatibility` 字段

可选的 `compatibility` 字段：

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

<Card>
  **示例：**

  ```yaml theme={null}
  compatibility: Designed for Claude Code (or similar products)
  ```

  ```yaml theme={null}
  compatibility: Requires git, docker, jq, and access to the internet
  ```
</Card>

<Note>
  大多数 skills 都不需要 `compatibility` 字段。
</Note>

#### `metadata` 字段

可选的 `metadata` 字段：

* 是一个从字符串键到字符串值的映射
* 客户端可以用它存储 Agent Skills 规范中未定义的附加属性
* 建议让键名具备一定唯一性，以避免意外冲突

<Card>
  **示例：**

  ```yaml theme={null}
  metadata:
    author: example-org
    version: "1.0"
  ```
</Card>

#### `allowed-tools` 字段

可选的 `allowed-tools` 字段：

* 一个以空格分隔的工具列表，表示这些工具已被预批准可执行
* 该字段属于实验性能力，不同 agent 实现对它的支持程度可能不同

<Card>
  **示例：**

  ```yaml theme={null}
  allowed-tools: Bash(git:*) Bash(jq:*) Read
  ```
</Card>

### 正文内容

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.)

尽量让单个[引用文件](#file-references)保持聚焦。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 根目录的路径：

```markdown SKILL.md theme={null}
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py
```

文件引用最好保持在相对 `SKILL.md` 的一层深度内，避免形成过深的引用链。

## 校验

使用 [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) 参考库来校验你的 skills：

```bash theme={null}
skills-ref validate ./my-skill
```

它会检查你的 `SKILL.md` frontmatter 是否有效，并确认是否遵循了所有命名约定。