> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmskills.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills Specification

> Agent Skills specification: Learn to create SKILL.md files with YAML frontmatter, define metadata, organize directories and build AI agent capabilities.

## Directory structure

An Agent Skill is a directory containing at minimum a `SKILL.md` file. This format is widely used for creating Claude Skills:

```
skill-name/
└── SKILL.md          # Required
```

<Tip>
  You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your Agent Skill.
</Tip>

## SKILL.md format

The `SKILL.md` file is the core component of every Agent Skill. It must contain YAML frontmatter followed by Markdown content.

### Frontmatter (required)

```yaml theme={null}
---
name: skill-name
description: A description of what this skill does and when to use it.
---
```

With optional fields:

```yaml theme={null}
---
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"
---
```

| 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 Agent 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 Agent 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 theme={null}
name: pdf-processing
```

```yaml theme={null}
name: data-analysis
```

```yaml theme={null}
name: code-review
```

Invalid examples:

```yaml theme={null}
name: PDF-Processing  # uppercase not allowed
```

```yaml theme={null}
name: -pdf  # cannot start with hyphen
```

```yaml theme={null}
name: pdf--processing  # consecutive hyphens not allowed
```

#### `description` field

The required `description` field:

* Must be 1-1024 characters
* Should describe both what the Agent Skill does and when to use it
* Should include specific keywords that help agents identify relevant tasks

Good example:

```yaml theme={null}
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 theme={null}
description: Helps with PDFs.
```

#### `license` field

The optional `license` field:

* Specifies the license applied to the Agent Skill
* We recommend keeping it short (either the name of a license or the name of a bundled license file)

Example:

```yaml theme={null}
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 Agent Skill has specific environment requirements
* Can indicate intended product, required system packages, network access needs, etc.

Examples:

```yaml theme={null}
compatibility: Designed for Claude Code (or similar products)
```

```yaml theme={null}
compatibility: Requires git, docker, jq, and access to the internet
```

<Note>
  Most Agent 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 specification. Claude Skills often use this field for custom versioning or author information.
* We recommend making your key names reasonably unique to avoid accidental conflicts

Example:

```yaml theme={null}
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 theme={null}
allowed-tools: Bash(git:*) Bash(jq:*) Read
```

### Body content

The Markdown body after the frontmatter contains the Agent Skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively when using this Agent Skill. This instruction set is what guides a Claude Skill through complex workflows.

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 an Agent Skill. Consider splitting longer `SKILL.md` content into referenced files.

## Optional directories

Agent Skills can include optional directories to support more complex workflows.

### scripts/

Contains executable code that agents can run when using the Agent Skill. 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. When agents use Agent Skills, they load these reference files on demand—a key principle for efficient Claude Skill execution.

### assets/

Contains static resources:

* Templates (document templates, configuration templates)
* Images (diagrams, examples)
* Data files (lookup tables, schemas)

## Progressive disclosure

Agent Skills should be structured for efficient use of context. This structure is essential for high-performance Claude Skills:

1. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all Agent Skills
2. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the Agent Skill or Claude 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 Agent Skill, use relative paths from the skill root:

```markdown theme={null}
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 Agent Skills and ensure your Claude Skills are correctly formatted:

```bash theme={null}
skills-ref validate ./my-skill
```

This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.