> ## Documentation Index
> Fetch the complete documentation index at: https://agentskills.ooos.top/llms.txt
> Use this file to discover all available pages before exploring further.
# 规范
> Agent Skills 的完整格式规范。
本文档定义了 Agent Skills 格式。
## 目录结构
一个 skill 是一个包含至少一个 `SKILL.md` 文件的目录：
```
skill-name/
└── SKILL.md # 必需
```
您可以选择性地包含 [附加目录](#optional-directories) 如 `scripts/`、`references/` 和 `assets/` 来支持您的 skill。
## SKILL.md 格式
`SKILL.md` 文件必须包含 YAML frontmatter，后跟 Markdown 内容。
### Frontmatter（必需）
```yaml theme={null}
---
name: skill-name
description: 对此 skill 的功能及使用时机的描述。
---
```
包含可选字段：
```yaml theme={null}
---
name: pdf-processing
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---
```
| 字段 | 必需 | 约束 |
| --------------- | -- | ------------------------------------ |
| `name` | 是 | 最多 64 个字符。仅限小写字母、数字和连字符。不得以连字符开头或结尾。 |
| `description` | 是 | 最多 1024 个字符。非空。描述 skill 的功能及使用时机。 |
| `license` | 否 | 许可证名称或对捆绑许可证文件的引用。 |
| `compatibility` | 否 | 最多 500 个字符。指示环境要求（预期产品、系统包、网络访问等）。 |
| `metadata` | 否 | 用于附加元数据的任意键值映射。 |
| `allowed-tools` | 否 | 预批准的 skill 可使用的工具的空格分隔列表。（实验性） |
#### `name` 字段
必需的 `name` 字段：
* 必须为 1-64 个字符
* 只能包含 unicode 小写字母数字字符和连字符（`a-z` 和 `-`）
* 不得以 `-` 开头或结尾
* 不得包含连续的连字符（`--`）
* 必须与父目录名称匹配
有效示例：
```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 # 不允许连续连字符
```
#### `description` 字段
必需的 `description` 字段：
* 必须为 1-1024 个字符
* 应描述 skill 的功能及使用时机
* 应包含帮助 agents 识别相关任务的特定关键词
良好示例：
```yaml theme={null}
description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
```
较差示例：
```yaml theme={null}
description: 帮助处理 PDF。
```
#### `license` 字段
可选的 `license` 字段：
* 指定应用于 skill 的许可证
* 我们建议保持简短（许可证名称或捆绑许可证文件的名称）
示例：
```yaml theme={null}
license: 专有。LICENSE.txt 包含完整条款
```
#### `compatibility` 字段
可选的 `compatibility` 字段：
* 如果提供，必须为 1-500 个字符
* 仅应在您的 skill 有特定环境要求时包含
* 可以指示预期产品、必需的系统包、网络访问需求等
示例：
```yaml theme={null}
compatibility: 专为 Claude Code（或类似产品）设计
```
```yaml theme={null}
compatibility: 需要 git、docker、jq 和互联网访问
```
大多数 skills 不需要 `compatibility` 字段。
#### `metadata` 字段
可选的 `metadata` 字段：
* 从字符串键到字符串值的映射
* 客户端可以使用此字段存储 Agent Skills 规范未定义的附加属性
* 我们建议使您的键名具有合理的唯一性以避免意外冲突
示例：
```yaml theme={null}
metadata:
author: example-org
version: "1.0"
```
#### `allowed-tools` 字段
可选的 `allowed-tools` 字段：
* 预批准可运行的工具的空格分隔列表
* 实验性。对此字段的支持可能因 agent 实现而异
示例：
```yaml theme={null}
allowed-tools: Bash(git:*) Bash(jq:*) Read
```
### 主体内容
frontmatter 之后的 Markdown 主体包含 skill 指令。没有格式限制。编写任何有助于 agents 有效执行任务的内容。
推荐的章节：
* 分步说明
* 输入和输出示例
* 常见边缘情况
请注意，一旦决定激活 skill，agent 将加载整个文件。考虑将较长的 `SKILL.md` 内容拆分到引用的文件中。
## 可选目录
### scripts/
包含 agents 可以运行的可执行代码。脚本应：
* 自包含或清楚地记录依赖项
* 包含有用的错误消息
* 优雅地处理边缘情况
支持的语言取决于 agent 实现。常见选项包括 Python、Bash 和 JavaScript。
### references/
包含 agents 在需要时可以阅读的附加文档：
* `REFERENCE.md` - 详细技术参考
* `FORMS.md` - 表单模板或结构化数据格式
* 领域特定文件（`finance.md`、`legal.md` 等）
保持单个 [参考文件](#file-references) 专注。agents 按需加载这些文件，因此较小的文件意味着更少的上下文使用。
### assets/
包含静态资源：
* 模板（文档模板、配置模板）
* 图像（图表、示例）
* 数据文件（查找表、模式）
## 渐进式披露
skills 应结构化以高效使用上下文：
1. **元数据**（约 100 个 token）：所有 skills 的 `name` 和 `description` 字段在启动时加载
2. **指令**（建议 \< 5000 个 token）：激活 skill 时加载完整的 `SKILL.md` 主体
3. **资源**（按需）：文件（例如 `scripts/`、`references/` 或 `assets/` 中的文件）仅在需要时加载
将您的主要 `SKILL.md` 保持在 500 行以下。将详细参考材料移动到单独的文件中。
## 文件引用
在引用 skill 中的其他文件时，使用相对于 skill 根目录的路径：
```markdown theme={null}
参见 [参考指南](references/REFERENCE.md) 了解详情。
运行提取脚本：
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 是否有效并遵循所有命名约定。