# 规范

URL: https://caijiao.org/agent-skills/specification
Source: docs/agent-skills/specification.md
Description: 智能体技能的完整格式规范。

本文档定义了智能体技能格式。

## 目录结构

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

```
skill-name/
└── SKILL.md          # 必需
```

您可以选择包含其他目录，如 `scripts/`、`references/` 和 `assets/` 来支持您的技能。

## SKILL.md 格式

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

### 前置元数据（必需）

```yaml
---
name: skill-name
description: 描述此技能的功能以及何时使用它。
---
```

带有可选字段：

```yaml
---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
```

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

#### `name` 字段

必需的 `name` 字段：

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

有效的示例：

```yaml
name: pdf-processing
```

```yaml
name: data-analysis
```

```yaml
name: code-review
```

无效的示例：

```yaml
name: PDF-Processing # 不允许使用大写字母
```

```yaml
name: -pdf # 不能以连字符开头
```

```yaml
name: pdf--processing # 不允许连续连字符
```

#### `description` 字段

必需的 `description` 字段：

- 必须为 1-1024 个字符
- 应同时描述技能的功能和何时使用它
- 应包含有助于智能体识别相关任务的特定关键字

好的示例：

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

不好的示例：

```yaml
description: 帮助处理 PDF。
```

#### `license` 字段

可选的 `license` 字段：

- 指定应用于技能的许可证
- 我们建议保持简短（许可证名称或捆绑许可证文件的名称）

示例：

```yaml
license: 专有。LICENSE.txt 包含完整条款
```

#### `compatibility` 字段

可选的 `compatibility` 字段：

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

示例：

```yaml
compatibility: 专为 Claude Code（或类似产品）设计
```

```yaml
compatibility: 需要 git、docker、jq 和互联网访问
```

大多数技能不需要 `compatibility` 字段。

#### `metadata` 字段

可选的 `metadata` 字段：

- 从字符串键到字符串值的映射
- 客户端可以使用它来存储智能体技能规范中未定义的附加属性
- 我们建议让您的键名保持合理的唯一性，以避免意外冲突

示例：

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

#### `allowed-tools` 字段

可选的 `allowed-tools` 字段：

- 预批准运行的工具的空格分隔列表
- 实验性。不同智能体实现对该字段的支持可能有所不同

示例：

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

### 正文内容

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

推荐部分：

- 分步说明
- 输入和输出示例
- 常见边缘情况

请注意，智能体一旦决定激活技能，就会加载整个文件。考虑将较长的 `SKILL.md` 内容拆分为引用文件。

## 可选目录

### scripts/

包含智能体可以运行的可执行代码。脚本应：

- 自包含或清晰记录依赖项
- 包含有用的错误消息
- 优雅地处理边缘情况

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

### references/

包含智能体在需要时可以阅读的附加文档：

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

保持各个参考文件专注。智能体根据需要加载这些文件，因此较小的文件意味着更少使用上下文。

### assets/

包含静态资源：

- 模板（文档模板、配置模板）
- 图像（图表、示例）
- 数据文件（查找表、架构）

## 渐进式披露

技能应结构化以高效使用上下文：

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

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

## 文件引用

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

```markdown
有关详细信息，请参阅 [参考指南](references/REFERENCE.md)。

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

将文件引用保持在 `SKILL.md` 下一级。避免深度嵌套的引用链。

## 验证

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

```bash
skills-ref validate ./my-skill
```

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