---
topic: agentskills-specification
source_keys:
  - agentskills-spec
---

## Frontmatter fields

| Field           | Required | Constraints |
|----------------|----------|-------------|
| `name`         | Yes      | 1–64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens (`--`). Must match the parent directory name. |
| `description`  | Yes      | 1–1024 characters. Describes what the skill does and when to use it. |
| `license`      | No       | License name or reference to a bundled license file. |
| `compatibility`| No       | 1–500 characters. Environment requirements: intended product, required system packages, network access needs. Most skills don't need this. |
| `metadata`     | No       | Arbitrary key-value map. Use for author, version, category, and any project extensions not defined by the spec. |
| `allowed-tools`| No       | Space-separated string of pre-approved tools. Experimental — support varies by client. |

## Minimal example

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

## Extended example

```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"
  category: document
allowed-tools: Bash(python3:*) Read Write
---
```

## name field rules

Valid: `pdf-processing`, `data-analysis`, `code-review`

Invalid:
- `PDF-Processing` — uppercase not allowed
- `-pdf` — cannot start with hyphen
- `pdf--processing` — consecutive hyphens not allowed

The `name` value must exactly match the parent directory name. A skill at `.agents/skills/my-tool/SKILL.md` must have `name: my-tool`.

## description field guidance

The description carries the entire burden of triggering. Agents read only `name` and `description` at startup. Write it as a trigger — describe both what the skill does and when to use it.

Good:
```yaml
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to explore,
  transform, or visualize the data, even if they don't explicitly mention
  "CSV" or "analysis."
```

Poor:
```yaml
description: Helps with PDFs.
```

Hard limit: 1024 characters. Descriptions tend to grow during optimization — check length before committing.

## Body content

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

The agent loads the entire body once the skill is activated. Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files in `references/` or similar directories.

## Optional directories

### `scripts/`

Executable code agents can run. Scripts should be self-contained, include helpful error messages, and handle edge cases gracefully. See the scripts reference for design guidance.

### `references/`

Additional documentation agents can read when needed. Keep files focused — agents load them on demand, so smaller files mean less context use. Common files: `REFERENCE.md`, `FORMS.md`, domain-specific files (`finance.md`, `legal.md`).

### `assets/`

Static resources: templates, images, data files (lookup tables, schemas).

## File references

Use relative paths from the skill root when referencing other files:

```markdown
See [the reference guide](references/REFERENCE.md) for details.
Run: scripts/extract.py
```

Keep references one level deep from `SKILL.md`. Avoid deeply nested reference chains.

## Progressive disclosure levels

1. **Metadata** (~100 tokens): `name` and `description` — loaded at startup for all skills
2. **Instructions** (<5000 tokens recommended): full `SKILL.md` body — loaded on activation
3. **Resources** (as needed): files in `scripts/`, `references/`, `assets/` — loaded only when required

## Validation

The `skills-ref` reference library validates `SKILL.md` frontmatter and naming conventions:

```bash
skills-ref validate ./my-skill
```

Source: `https://github.com/agentskills/agentskills/tree/main/skills-ref`