239 lines
6.0 KiB
Markdown
239 lines
6.0 KiB
Markdown
# 规范说明
|
||
|
||
> Agent Skills 的完整格式规范。
|
||
|
||
本文档定义了 Agent Skills 格式规范。
|
||
|
||
## 目录结构
|
||
|
||
一个技能是一个目录，至少包含一个 `SKILL.md` 文件：
|
||
|
||
```
|
||
skill-name/
|
||
└── SKILL.md # 必需
|
||
```
|
||
|
||
<Tip>
|
||
你可以选择性地包含[额外的目录](#可选目录)，如 `scripts/`、`references/` 和 `assets/` 来支持你的技能。
|
||
</Tip>
|
||
|
||
## SKILL.md 格式
|
||
|
||
`SKILL.md` 文件必须包含 YAML 前置数据（frontmatter），后跟 Markdown 内容。
|
||
|
||
### 前置数据（必需）
|
||
|
||
```yaml
|
||
---
|
||
name: skill-name
|
||
description: A description of what this skill does and when to use it.
|
||
---
|
||
```
|
||
|
||
包含可选字段：
|
||
|
||
```yaml
|
||
---
|
||
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'
|
||
---
|
||
```
|
||
|
||
| 字段 | 是否必需 | 约束条件 |
|
||
| --------------- | -------- | -------------------------------------------------------------------- |
|
||
| `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: 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
|
||
description: Helps with PDFs.
|
||
```
|
||
|
||
#### `license` 字段
|
||
|
||
可选的 `license` 字段：
|
||
|
||
- 指定应用于该技能的许可证
|
||
- 我们建议保持简短（要么是许可证名称，要么是打包许可证文件的名称）
|
||
|
||
示例：
|
||
|
||
```yaml
|
||
license: Proprietary. LICENSE.txt has complete terms
|
||
```
|
||
|
||
#### `compatibility` 字段
|
||
|
||
可选的 `compatibility` 字段：
|
||
|
||
- 如果提供，必须为 1-500 个字符
|
||
- 仅在你的技能具有特定环境要求时才应包含
|
||
- 可以指示目标产品、所需的系统包、网络访问需求等
|
||
|
||
示例：
|
||
|
||
```yaml
|
||
compatibility: Designed for Claude Code (or similar products)
|
||
```
|
||
|
||
```yaml
|
||
compatibility: Requires git, docker, jq, and access to the internet
|
||
```
|
||
|
||
<Note>
|
||
大多数技能不需要 `compatibility` 字段。
|
||
</Note>
|
||
|
||
#### `metadata` 字段
|
||
|
||
可选的 `metadata` 字段：
|
||
|
||
- 从字符串键到字符串值的映射
|
||
- 客户端可以使用它来存储未由 Agent Skills 规范定义的附加属性
|
||
- 我们建议使你的键名足够唯一以避免意外冲突
|
||
|
||
示例：
|
||
|
||
```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 tokens）：所有技能在启动时加载 `name` 和 `description` 字段
|
||
2. **指令**（建议 < 5000 tokens）：技能激活时加载完整的 `SKILL.md` 正文
|
||
3. **资源**（按需）：文件（例如 `scripts/`、`references/` 或 `assets/` 中的文件）仅在需要时加载
|
||
|
||
将主 `SKILL.md` 保持在 500 行以下。将详细参考资料移动到单独的文件中。
|
||
|
||
## 文件引用
|
||
|
||
在技能中引用其他文件时，使用从技能根目录开始的相对路径：
|
||
|
||
```markdown
|
||
Run the extraction script:
|
||
scripts/extract.py
|
||
```
|
||
|
||
保持文件引用从 `SKILL.md` 开始只有一层深度。避免深度嵌套的引用链。
|