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).