---
name: agentskills-spec-authoring
source: https://app.decimal.ai/s/agentskills-spec-authoring@1/SKILL.md
source_sha256: 2983d4dc49bc
---

# agentskills.io SKILL.md conventions

## Contract

Every Agent Skill's `SKILL.md` must match the agentskills.io specification exactly. This
governs the YAML frontmatter shape, the trigger-phrase keyword, the directory layout, the
reference-linking form, and the token budgets. Apply whenever you create, edit, or review a
`SKILL.md`. The spec's choices are arbitrary and differ from the generic defaults a model
reaches for — match them precisely.

## Rules

### Frontmatter — required fields

- The frontmatter contains exactly two required fields: `name` and `description`. Nothing
  else is required.
- `name`:
  - 1–64 characters.
  - Lowercase letters, digits, and hyphens only (`a-z`, `0-9`, `-`). No spaces, no
    underscores, no capitals.
  - Must not start or end with `-`.
  - Must not contain consecutive hyphens (`--`).
  - Must match the skill's parent directory name exactly.
  - Must not start with the reserved prefixes `claude-` or `anthropic-`.
- `description`:
  - 1–1024 characters, and 60 words or fewer (cross-model density).
  - Written as an inline double-quoted string. Never a YAML folded scalar (`>-`) or block
    scalar (`|`).
  - States WHAT the skill does first, then the literal keyword `WHEN:`.
  - No XML angle brackets (`< >`) anywhere in the frontmatter.

### Frontmatter — triggers

- After WHAT, append the literal keyword `WHEN:` followed by concrete trigger phrases, each
  wrapped in double quotes: `WHEN: "create a skill", "review a skill PR"`.
- `WHEN:` is the preferred trigger marker. `USE FOR:` is accepted but not preferred; do not
  reach for it by default.
- Do not add a `DO NOT USE FOR:` clause. The sole exception: a specialized skill that shares
  trigger phrases with a broader skill needs `DO NOT USE FOR:` to avoid the broader skill
  capturing its prompts. Outside that disambiguation case it causes keyword contamination.

### Frontmatter — optional fields

- Allowed optional keys: `license`, `compatibility`, and a `metadata` map (e.g.
  `metadata.author`, `metadata.version`). They are optional — omit when unused, never invent
  others.

### Files and directories

- The instruction file is named exactly `SKILL.md`. Not `README.md`, not `skill.md`, not
  `Skill.md`.
- Supporting documentation goes in a `references/` directory. Executable code goes in a
  `scripts/` directory. Output templates go in `templates/`; data files in `assets/`. Use
  those exact directory names — never `docs/`, `lib/`, `bin/`, or `src/`.
- Files inside `references/` use lowercase-hyphen names (`api-reference.md`, not
  `APIReference.md`).
- Keep references one level deep; avoid chains like `references/detail/more/file.md`.

### Reference links

- Link to a specific file, never a bare folder: `[API notes](references/api.md)`, never
  `[API notes](references/api/)`. A folder link does not load any content.
- For folder-organized content, link the folder's `README.md`:
  `[Recipes](references/recipes/README.md)`.
- Use descriptive link text, not the path repeated as the text. `[the API reference](references/api.md)`,
  not `[references/api.md](references/api.md)`.
- References load just-in-time: only explicitly linked files load, the whole file loads at
  once (anchors are hints only), and nothing is cached between requests — so write each
  reference file as a self-contained unit.

### Token budgets

- `SKILL.md`: target under ~500 tokens (soft), hard ceiling ~5000 tokens. Limits are in
  tokens, not words.
- `references/*.md`: under ~1000 tokens each (soft), ~2000 hard. When a reference exceeds the
  limit, split it into a folder with a `README.md` entry point.

## Worked examples

### Name shape (BEFORE → AFTER)

```yaml
# BEFORE — generic default
name: PDF_Table_Extractor
```
```yaml
# AFTER — agentskills.io-compliant (lowercase, hyphens, matches directory)
name: pdf-table-extractor
```

### Description scalar form (BEFORE → AFTER)

```yaml
# BEFORE — folded scalar, prose "Use it when", no WHEN: keyword
description: >-
  This skill helps users extract structured data and tables from PDF
  files. Use it whenever someone needs to parse or read a PDF document.
```
```yaml
# AFTER — inline double-quoted, WHAT first, then WHEN: with quoted phrases
description: "Extracts structured data and tables from PDF files. WHEN: \"parse a PDF\", \"extract tables from PDF\", \"read a PDF document\"."
```

### Trigger keyword (BEFORE → AFTER)

```yaml
# BEFORE — vague "Use for" prose, unquoted phrases
description: "Reviews Terraform plans. Use for checking risky changes and drift."
```
```yaml
# AFTER — literal WHEN:, each phrase double-quoted
description: "Reviews Terraform plans for risky changes. WHEN: \"review a terraform plan\", \"check for risky changes\", \"detect drift\"."
```

### Instruction file name (BEFORE → AFTER)

```
# BEFORE
my-skill/README.md
```
```
# AFTER
my-skill/SKILL.md
```

### Directory names (BEFORE → AFTER)

```
# BEFORE
my-skill/docs/api.md
my-skill/bin/helper.sh
```
```
# AFTER
my-skill/references/api.md
my-skill/scripts/helper.sh
```

### Reference link form (BEFORE → AFTER)

```markdown
<!-- BEFORE — folder link (loads nothing) and path-as-text -->
See [references/recipes/](references/recipes/) for options.
```
```markdown
<!-- AFTER — file link with descriptive text -->
See [the recipes index](references/recipes/README.md) for options.
```

### Oversized reference (BEFORE → AFTER)

```
# BEFORE — one 1500-token file
references/large-guide.md
```
```
# AFTER — split into a folder with a README entry point
references/large-guide/README.md   # overview + links
references/large-guide/setup.md
references/large-guide/usage.md
```

## Edge cases & exceptions

- **DO NOT USE FOR: is required, not banned, for disambiguation.** When a narrow skill and a
  broad skill both match the same prompt (e.g. both match "deploy to Azure"), the narrow
  skill must keep a `DO NOT USE FOR:` clause or the broad skill steals its prompts. Run the
  routing/integration tests before removing such a clause.
- **`USE FOR:` is valid, just not preferred.** Existing skills using `USE FOR:` are
  compliant; prefer `WHEN:` for new work and cross-model compatibility.
- **Directory name is the source of truth for `name`.** If the directory is `my-skill`, the
  `name` field must be `my-skill` — fix whichever is wrong, but they must agree.
- **Anchors in links are hints only.** `[guide](references/guide.md#setup)` still loads the
  entire file; never rely on partial loading.
- **Metadata loads at startup for every skill.** Keep `description` keyword-rich but short;
  front-load the most distinctive trigger phrases since not all skills stay visible under
  token limits.

## Do / Don't

- Never write `name: My-Skill` or `name: my_skill`; always `name: my-skill`.
- Never use a folded (`>-`) or block (`|`) scalar for `description`; always an inline
  double-quoted string.
- Never describe triggers in prose ("use it whenever…"); always the literal `WHEN:` keyword
  with double-quoted phrases.
- Never name the instruction file `README.md`; always `SKILL.md`.
- Never use `docs/`, `lib/`, or `bin/`; always `references/` and `scripts/`.
- Never link a bare folder ending in `/`; always link a specific `.md` file.
- Never add `DO NOT USE FOR:` by default; only for genuine trigger overlap.
- Never exceed 60 words in `description`; always lead with WHAT, then `WHEN:`.

## Common mistakes

- Title-casing or underscoring the `name` (`PDF-Extractor`, `pdf_extractor`).
- Using a multi-line folded `>-` description because it "reads nicer."
- Writing "Use this when…" prose instead of the literal `WHEN:` keyword.
- Leaving trigger phrases unquoted after `WHEN:`.
- Naming the file `README.md` out of habit.
- Putting docs in `docs/` and scripts in `bin/`.
- Linking `references/recipes/` (folder) and assuming content loads.
- Repeating the path as the link text, wasting tokens.
- Letting `description` run well past 60 words.

## Quick checklist

- [ ] `name`: lowercase/digits/hyphens, no `--`, no leading/trailing `-`, matches directory, not `claude-`/`anthropic-`.
- [ ] `description`: inline double-quoted, ≤60 words, WHAT then `WHEN:` with quoted phrases, no `< >`.
- [ ] No `USE FOR:` (prefer `WHEN:`); no `DO NOT USE FOR:` unless disambiguating.
- [ ] Instruction file is `SKILL.md`; docs in `references/`, code in `scripts/`.
- [ ] Reference links point to specific files, not bare folders; descriptive link text.
- [ ] `SKILL.md` < ~500 tokens; each reference < ~1000 tokens (split into a folder + README if larger).