SKILL.md frontmatter, field by field
The frontmatter is how an agent decides whether a skill applies. Two fields are required; the rest narrow behaviour or carry your own bookkeeping.
Every field
The complete set. Anything else you add is preserved but ignored.
| Field | Required | What it does |
|---|---|---|
name | Yes | The skill's identifier. Lowercase, hyphenated, unique within your library. |
description | Yes | When to use the skill. This is what an agent matches against, and the highest-leverage field in the file. |
allowed-tools | No | Narrows which tools the agent may use while this skill is active. |
license | No | A licence identifier, for skills you intend to share. |
compatibility | No | Assumptions the skill makes about its inputs or environment. |
metadata | No | A free-form string map for your own bookkeeping. Never read by the agent. |
name
The identifier. It is also the folder name the skill is written to at every destination, which is why the rules are strict:
- Lowercase letters, digits and single hyphens only: no uppercase, no underscores, no consecutive hyphens.
- 1 to 64 characters.
anthropicandclaudeare reserved. Pick something that names the job instead.
name: pdf-review-checklist # valid
name: PDF-Review # invalid — uppercase
name: pdf--review # invalid — double hyphen
name: claude # invalid — reservedName the job, not the tool: pdf-review-checklist tells a reader what the skill does, helper-2 does not.
description
Required, and the field to spend your time on. An agent picks a skill by reading descriptions; it does not read bodies first. A description that does not describe a situation gives it nothing to match against.
The difference in practice:
# Weak — states a topic, gives the agent no trigger
description: Contract review.
# Strong — names the situation that should invoke it
description: Use when the user asks for a contract or PDF to be reviewed. Walks
the standard clause checklist and reports findings by severity.- Name the trigger. Phrases like "Use when the user…" or "For tasks involving…" are what make a skill fire at the right moment.
- Write in the third person. Describe what the skill does, not what you will do.
- Up to 1024 characters. Long is allowed; use the room to cover the cases that should trigger it.
Under-triggering is silent
allowed-tools
Optional. A space-separated list of tool tokens the agent may use while the skill is active. Omit it and the skill inherits whatever the agent already has. See allowed-tools for the grammar and how to scope it.
allowed-tools: Read Grep Bash(git:*)license, compatibility, metadata
Three fields that carry information rather than change behaviour:
| Field | Notes |
|---|---|
license | A licence identifier such as MIT. Worth setting on anything you intend to share outside your team. |
compatibility | Up to 500 characters. Assumptions the skill makes: input formats, size limits, a language. Read by people, not enforced. |
metadata | A map of string keys to string values, for ownership, review cycles, ticket references. Never read by the agent, so use it freely. |
---
name: pdf-review-checklist
description: Use when the user asks for a contract to be reviewed…
allowed-tools: Read Grep
license: MIT
compatibility: Assumes contracts are English-language and under 100 pages.
metadata:
owner: legal-ops
review-cycle: quarterly
---Fields we do not recognise
Any key we do not recognise is preserved exactly as written. A skill imported from elsewhere keeps its extra frontmatter through an edit-and-publish round trip, comments and key order included.
Preserved is not the same as understood