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

# 规范

> Agent Skills 的完整格式规范。

## 目录结构

技能是一个包含至少一个 `SKILL.md` 文件的目录：

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

## `SKILL.md` 格式

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

### 前置元数据

| 字段              | 是否必需 | 约束                                         |
| --------------- | ---- | ------------------------------------------ |
| `name`          | 是    | 最多 64 个字符。仅可包含小写字母、数字和连字符。不得以下划线或连字符开头或结尾。 |
| `description`   | 是    | 最多 1024 个字符。不能为空。描述该技能做什么以及何时使用。           |
| `license`       | 否    | 许可证名称或对捆绑许可证文件的引用。                         |
| `compatibility` | 否    | 最多 500 个字符。指示环境要求（预期产品、系统包、网络访问等）。         |
| `metadata`      | 否    | 任意键值映射，用于额外元数据。                            |
| `allowed-tools` | 否    | 以空格分隔的预先批准工具字符串，技能可使用它们。（实验性）              |

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

  ```markdown SKILL.md theme={null}
  ---
  name: 技能名称
  description: 关于此技能做什么以及何时使用的描述。
  ---
  ```

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

  ```markdown SKILL.md theme={null}
  ---
  name: pdf-processing
  description: 提取 PDF 文本，填写表单，合并文件。处理 PDF 时使用。
  license: Apache-2.0
  metadata:
    author: example-org
    version: "1.0"
  ---
  ```
</Card>

#### `name` 字段

必需的 `name` 字段：

* 必须为 1-64 个字符
* 仅可包含 Unicode 小写字母数字字符（`a-z`、`0-9`）和连字符（`-`）
* 不得以连字符（`-`）开头或结尾
* 不得包含连续连字符（`--`）
* 必须与父目录名称匹配

<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  # 不允许大写
  ```

  ```yaml theme={null}
  name: -pdf  # 不能以连字符开头
  ```

  ```yaml theme={null}
  name: pdf--processing  # 不允许连续连字符
  ```
</Card>

#### `description` 字段

必需的 `description` 字段：

* 必须为 1-1024 个字符
* 应描述技能的作用以及何时使用它
* 应包含帮助代理识别相关任务的具体关键词

<Card>
  **好示例：**

  ```yaml theme={null}
  description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，并合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
  ```

  **差示例：**

  ```yaml theme={null}
  description: 帮助处理 PDF。
  ```
</Card>

#### `license` 字段

可选的 `license` 字段：

* 指定应用于技能的许可证
* 我们建议保持简短（要么是许可证名称，要么是捆绑许可证文件的名称）

<Card>
  **示例：**

  ```yaml theme={null}
  license: 专有。LICENSE.txt 包含完整条款
  ```
</Card>

#### `compatibility` 字段

可选的 `compatibility` 字段：

* 如果提供，必须为 1-500 个字符
* 仅当您的技能有特定环境要求时才应包含
* 可以指示预期产品、所需的系统包、网络访问需求等。

<Card>
  **示例：**

  ```yaml theme={null}
  compatibility: 专为 Claude Code（或类似产品）设计
  ```

  ```yaml theme={null}
  compatibility: 需要 git、docker、jq 以及互联网访问权限
  ```

  ```yaml theme={null}
  compatibility: 需要 Python 3.14+ 和 uv
  ```
</Card>

<Note>
  大多数技能不需要 `compatibility` 字段。
</Note>

#### `metadata` 字段

可选的 `metadata` 字段：

* 从字符串键到字符串值的映射
* 客户端可使用此字段存储 Agent Skills 规范未定义的附加属性
* 我们建议使键名具有合理的独特性，以避免意外冲突

<Card>
  **示例：**

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

#### `allowed-tools` 字段

可选的 `allowed-tools` 字段：

* 一个以空格分隔的工具字符串，这些工具是预先批准可运行的
* 实验性。不同的代理实现对该字段的支持可能不同

<Card>
  **示例：**

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

### 正文内容

前置元数据后的 Markdown 正文包含技能指令。没有格式限制。编写任何能帮助代理有效执行任务的内容。

推荐部分：

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

请注意，代理一旦决定激活技能，将加载整个文件。考虑将较长的 `SKILL.md` 内容拆分到引用文件中。

## 可选目录

### `scripts/`

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

* 自包含或清楚记录依赖项
* 包含有帮助的错误消息
* 优雅地处理边缘情况

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

### `references/`

包含代理在需要时可阅读的附加文档：

* `REFERENCE.md` - 详细技术参考
* `FORMS.md` - 表单模板或结构化数据格式
* 特定领域文件（`finance.md`、`legal.md` 等）

保持单个 [参考文件](#file-references) 专注。代理按需加载这些文件，因此较小的文件意味着更少占用上下文。

### `assets/`

包含静态资源：

* 模板（文档模板、配置模板）
* 图像（图表、示例）
* 数据文件（查找表、模式）

## 渐进式披露

代理会逐步加载技能，只有在任务需要时才引入更多细节。技能应设计为充分利用这一点：

1. **元数据**（约 100 个 token）：启动时会为所有技能加载 `name` 和 `description` 字段
2. **指令**（建议 \< 5000 个 token）：在技能激活时加载 `SKILL.md` 正文
3. **资源**（按需）：仅在需要时加载 `scripts/`、`references/` 或 `assets/` 中的文件

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

## 文件引用

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

```markdown SKILL.md theme={null}
参见 [参考指南](references/REFERENCE.md) 以获取详情。

运行提取脚本：
scripts/extract.py
```

保持文件引用从 `SKILL.md` 起只有一层深度。避免深层嵌套的引用链。

## 验证

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

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

这将检查您的 `SKILL.md` 前置元数据是否有效并遵循所有命名约定。