mirror of
https://github.com/agentskills/agentskills.git
synced 2026-06-18 15:54:06 +08:00
Koichi ITO
22d6aeb353
The example `description` values in what-are-skills.mdx and specification.mdx only described what the skill does, but omitted when to use it. This contradicted the spec's own guidance that description should cover both. Added a "Use when..." clause while keeping the line short enough to avoid clipping in the rendered code block on the docs site.
229 lines
6.4 KiB
Plaintext
229 lines
6.4 KiB
Plaintext
---
|
|
title: "Specification"
|
|
description: "The complete format specification for Agent Skills."
|
|
---
|
|
|
|
This document defines the Agent Skills format.
|
|
|
|
## Directory structure
|
|
|
|
A skill is a directory containing at minimum a `SKILL.md` file:
|
|
|
|
```
|
|
skill-name/
|
|
└── SKILL.md # Required
|
|
```
|
|
|
|
<Tip>
|
|
You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill.
|
|
</Tip>
|
|
|
|
## SKILL.md format
|
|
|
|
The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
|
|
|
|
### Frontmatter (required)
|
|
|
|
```yaml
|
|
---
|
|
name: skill-name
|
|
description: A description of what this skill does and when to use it.
|
|
---
|
|
```
|
|
|
|
With optional fields:
|
|
|
|
```yaml
|
|
---
|
|
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"
|
|
---
|
|
```
|
|
|
|
| Field | Required | Constraints |
|
|
|-------|----------|-------------|
|
|
| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
|
|
| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
|
|
| `license` | No | License name or reference to a bundled license file. |
|
|
| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
|
|
| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
|
|
| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) |
|
|
|
|
#### `name` field
|
|
|
|
The required `name` field:
|
|
- Must be 1-64 characters
|
|
- May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`)
|
|
- Must not start or end with `-`
|
|
- Must not contain consecutive hyphens (`--`)
|
|
- Must match the parent directory name
|
|
|
|
Valid examples:
|
|
```yaml
|
|
name: pdf-processing
|
|
```
|
|
```yaml
|
|
name: data-analysis
|
|
```
|
|
```yaml
|
|
name: code-review
|
|
```
|
|
|
|
Invalid examples:
|
|
```yaml
|
|
name: PDF-Processing # uppercase not allowed
|
|
```
|
|
```yaml
|
|
name: -pdf # cannot start with hyphen
|
|
```
|
|
```yaml
|
|
name: pdf--processing # consecutive hyphens not allowed
|
|
```
|
|
|
|
#### `description` field
|
|
|
|
The required `description` field:
|
|
- Must be 1-1024 characters
|
|
- Should describe both what the skill does and when to use it
|
|
- Should include specific keywords that help agents identify relevant tasks
|
|
|
|
Good example:
|
|
```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.
|
|
```
|
|
|
|
Poor example:
|
|
```yaml
|
|
description: Helps with PDFs.
|
|
```
|
|
|
|
#### `license` field
|
|
|
|
The optional `license` field:
|
|
- Specifies the license applied to the skill
|
|
- We recommend keeping it short (either the name of a license or the name of a bundled license file)
|
|
|
|
Example:
|
|
```yaml
|
|
license: Proprietary. LICENSE.txt has complete terms
|
|
```
|
|
|
|
#### `compatibility` field
|
|
|
|
The optional `compatibility` field:
|
|
- Must be 1-500 characters if provided
|
|
- Should only be included if your skill has specific environment requirements
|
|
- Can indicate intended product, required system packages, network access needs, etc.
|
|
|
|
Examples:
|
|
```yaml
|
|
compatibility: Designed for Claude Code (or similar products)
|
|
```
|
|
```yaml
|
|
compatibility: Requires git, docker, jq, and access to the internet
|
|
```
|
|
|
|
<Note>
|
|
Most skills do not need the `compatibility` field.
|
|
</Note>
|
|
|
|
#### `metadata` field
|
|
|
|
The optional `metadata` field:
|
|
- A map from string keys to string values
|
|
- Clients can use this to store additional properties not defined by the Agent Skills spec
|
|
- We recommend making your key names reasonably unique to avoid accidental conflicts
|
|
|
|
Example:
|
|
```yaml
|
|
metadata:
|
|
author: example-org
|
|
version: "1.0"
|
|
```
|
|
|
|
#### `allowed-tools` field
|
|
|
|
The optional `allowed-tools` field:
|
|
- A space-delimited list of tools that are pre-approved to run
|
|
- Experimental. Support for this field may vary between agent implementations
|
|
|
|
Example:
|
|
```yaml
|
|
allowed-tools: Bash(git:*) Bash(jq:*) Read
|
|
```
|
|
|
|
### Body content
|
|
|
|
The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
|
|
|
|
Recommended sections:
|
|
- Step-by-step instructions
|
|
- Examples of inputs and outputs
|
|
- Common edge cases
|
|
|
|
Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files.
|
|
|
|
## Optional directories
|
|
|
|
### scripts/
|
|
|
|
Contains executable code that agents can run. Scripts should:
|
|
- Be self-contained or clearly document dependencies
|
|
- Include helpful error messages
|
|
- Handle edge cases gracefully
|
|
|
|
Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
|
|
|
|
### references/
|
|
|
|
Contains additional documentation that agents can read when needed:
|
|
- `REFERENCE.md` - Detailed technical reference
|
|
- `FORMS.md` - Form templates or structured data formats
|
|
- Domain-specific files (`finance.md`, `legal.md`, etc.)
|
|
|
|
Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context.
|
|
|
|
### assets/
|
|
|
|
Contains static resources:
|
|
- Templates (document templates, configuration templates)
|
|
- Images (diagrams, examples)
|
|
- Data files (lookup tables, schemas)
|
|
|
|
## Progressive disclosure
|
|
|
|
Skills should be structured for efficient use of context:
|
|
|
|
1. **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills
|
|
2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
|
|
3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
|
|
|
|
Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
|
|
|
|
## File references
|
|
|
|
When referencing other files in your skill, use relative paths from the skill root:
|
|
|
|
```markdown
|
|
See [the reference guide](references/REFERENCE.md) for details.
|
|
|
|
Run the extraction script:
|
|
scripts/extract.py
|
|
```
|
|
|
|
Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
|
|
|
|
## Validation
|
|
|
|
Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
|
|
|
|
```bash
|
|
skills-ref validate ./my-skill
|
|
```
|
|
|
|
This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
|