MiscellaneousVerified21,079 stars

agentskills-spec

agentskills/agentskills

The complete format specification for Agent Skills.

Source preview

Raw content from the repository file

---
title: "Specification"
description: "The complete format specification for Agent Skills."
---

## Directory structure

A skill is a directory containing, at minimum, a `SKILL.md` file:

```
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories
```

## `SKILL.md` format

The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.

### Frontmatter

| 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-separated string of pre-approved tools the skill may use. (Experimental) |

<Card>
**Minimal example:**

```markdown SKILL.md
---
name: skill-name
description: A description of what this skill does and when to use it.
---
```

**Example with optional fields:**

```markdown SKILL.md
---
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"
---
```
</Card>

#### `name` field

The required `name` field:
- Must be 1-64 characters
- May only contain unicode lowercase alphanumeric characters (`a-z`, `0-9`) and hyphens (`-`)
- Must not start or end with a hyphen (`-`)
- Must not contain consecutive hyphens (`--`)
- Must match the parent directory name

<Card>
**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
```
</Card>

#### `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

<Card>
**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.
```
</Card>

#### `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)

<Card>
**Example:**
```yaml
license: Proprietary. LICENSE.txt has complete terms
```
</Card>

#### `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.

<Card>
**Examples:**
```yaml
compatibility: Designed for Claude Code (or similar products)
```
```yaml
compatibility: Requires git, docker, jq, and access to the internet
```
```yaml
compatibility: Requires Python 3.14+ and uv
```
</Card>

<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

<Card>
**Example:**
```yaml
metadata:
  author: example-org
  version: "1.0"
```
</Card>

#### `allowed-tools` field

The optional `allowed-tools` field:
- A space-separated string of tools that are pre-approved to run
- Experimental. Support for this field may vary between agent implementations

<Card>
**Example:**
```yaml
allowed-tools: Bash(git:*) Bash(jq:*) Read
```
</Card>

### 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

Agents load skills *progressively*, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this:

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 SKILL.md
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.

Source preview

Raw content from the repository file

--- title: "Specification" description: "The complete format specification for Agent Skills." --- ## Directory structure A skill is a directory containing, at minimum, a `SKILL.md` file: ``` skill-name/ ├── SKILL.md # Required: metadata + instructions ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation ├── assets/ # Optional: templates, resources └── ... # Any additional files or directories ``` ## `SKILL.md` format The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. ### Frontmatter | 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-separated string of pre-approved tools the skill may use. (Experimental) | <Card> **Minimal example:** ```markdown SKILL.md --- name: skill-name description: A description of what this skill does and when to use it. --- ``` **Example with optional fields:** ```markdown SKILL.md --- 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" --- ``` </Card> #### `name` field The required `name` field: - Must be 1-64 characters - May only contain unicode lowercase alphanumeric characters (`a-z`, `0-9`) and hyphens (`-`) - Must not start or end with a hyphen (`-`) - Must not contain consecutive hyphens (`--`) - Must match the parent directory name <Card> **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 ``` </Card> #### `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 <Card> **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. ``` </Card> #### `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) <Card> **Example:** ```yaml license: Proprietary. LICENSE.txt has complete terms ``` </Card> #### `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. <Card> **Examples:** ```yaml compatibility: Designed for Claude Code (or similar products) ``` ```yaml compatibility: Requires git, docker, jq, and access to the internet ``` ```yaml compatibility: Requires Python 3.14+ and uv ``` </Card> <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 <Card> **Example:** ```yaml metadata: author: example-org version: "1.0" ``` </Card> #### `allowed-tools` field The optional `allowed-tools` field: - A space-separated string of tools that are pre-approved to run - Experimental. Support for this field may vary between agent implementations <Card> **Example:** ```yaml allowed-tools: Bash(git:*) Bash(jq:*) Read ``` </Card> ### 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 Agents load skills *progressively*, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this: 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 SKILL.md 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.