- https://agentskills.io/home
# Agent Skills
## Overview
- Agent skill 的组成：一个目录，包含了：
- instructions
- scripts
- resources
- agent 可以 discover 和使用 skill，来精准和高效地完成工作。
- 开放标准，可以跨不同的 agents 使用。
## What are skills
- 一个 skill 是一个包含了 `SKILL.md` 文件的目录。
- `SKILL.md` 包含了
- metadata：name 和 description
- instructions：指示 agent 如何执行某个特定的任务。
- Skills can also bundle scripts, templates, and reference materials.
### How skills work
- 使用 **progressive disclosure** 来有效地管理 context
1. **Discovery**：启动时，agent 只加载 skill 的名字和描述
2. **Activation**：当 task 匹配 skill 的描述时，agent 将完整的 `SKILL.md`instructions读取到 context
3. **Execution**：agent 遵循 instructions，==按需==加载引用的文件或执行 bundled code
- 目的：fast & access to more context on demand
## The SKILL.md file
- 由起始的 YAML frontmatter 和 Markdown instructions 组成。
- YAML frontmatter：
- name: short id
- description: 何时使用该 skill
- Body：实际的 instructions
> [!NOTE]- SKILL.md example
> ```
> ---
> name: pdf-processing
> description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
> ---
>
> # PDF Processing
>
> ## When to use this skill
> Use this skill when the user needs to work with PDF files...
>
> ## How to extract text
> 1. Use pdfplumber for text extraction...
>
> ## How to fill forms
> ...
> ```
----
# Sepecification
## Directory structure
```
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
```
## SKILL.md format
### Frontmatter
| Field | Required | Constraints |
| ------------- | -------- | --------------------------------------------------------------------- |
| name | ✅ | 最多 64 字符，只能包含==小写==字母数字和连字符。必须跟父目录名一样。起始和结尾不能是连字符，不允许连续的连字符。 |
| description | ✅ | 最多 1024 字符。不能为空。描述 SKILL的作用以及何时使用它。 |
| license | ❌ | License name or reference to a bundled license file. |
| compatibility | ❌ | 最多 500 字符。指示环境要求（intended product, system packages, network access 等） |
| metadata | ❌ | 附加元数据，任何 KV mapping |
| allowed-tools | ❌ | SKILL 可能使用的 pre-approved tool list（空格分割） |
> [!NOTE]- frontmatter example
> ```
> ---
> 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"
> ---
> ```
### Body content
- skill instructions，无格式限制。
- Recommended sections：
- Step-by-step instructions
- Examples of inputs and outpus
- Common edge cases
- Skill 激活时会全部加载。可以考虑将较长的 `SKILL.md` 拆分到 referenced files 中。
## Optional directories
- **`scripts/`**：agent 可以运行的可执行代码。
- 需要：
- self-contained 或者 有清晰的依赖文档
- 包含 helpful error messages
- 优雅地处理边界情况
- 能支持的语言取决于 agent 的实现
- **`references`：** 附加的文档，agent 可以按需读取。
- `REFERENCE.md`：Detailed technical reference
- `FORM.md`：Form templates or structured data formats
- Domain-specific files：如 finance.md, legal.md 等
- **`asserts/`：** 静态资源，包含
- templates
- images
- data files
## Progressive disclosure
- 三级组织：
1. Metadata：~100 tokens，agent启动时加载 name + desc
2. Instructions：推荐 < 5000 tokens，激活时加载 `SKILL.md` body
3. Resources：按需加载
## File references
- 使用==相对路径==引用 skill 目录下的其他文件。
```
See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script:
scripts/extract.py
```
- Avoid nested reference chains。
## Validation
- 使用 [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) 来验证 skill
- `skills-ref validate ./my-skill`
- 验证 SKILL.md frontmatter 是否有效，且符合所有命名约定。