Claude Skill Front-Matter: Full Field Reference
Every SKILL.md opens with a YAML front-matter block between two --- lines, and that block is the only part of the skill the runtime reads before deciding whether to load the rest. Getting it wrong means a skill that never triggers, or never loads at all. This post is a field-by-field reference: what each field does, the rules that apply, and the YAML mistakes that quietly break skills.
For the full authoring workflow around the front-matter, see writing a Claude skill from scratch.
TL;DR: Two fields do almost all the work: name, a short lowercase hyphenated identifier that must match expectations for the folder name, and description, the single most important line in the whole skill because it is what Claude scans when deciding whether to load it. Write the description in third person, state both what the skill does and when to use it, and include the trigger words users actually type. Additional metadata fields such as version or author information may be supported depending on the environment; unknown fields are generally safer to include than malformed YAML, which can stop the skill loading entirely. Validate the YAML before shipping, keep the description under the length limit, and never put workflow instructions in the front-matter; those belong in the body below it.
The anatomy of a front-matter block
name: meeting-summariser
description: Summarises meeting transcripts into decisions, actions, and owners. Use when the user shares a transcript or asks for meeting notes, minutes, or action items.
Everything between the --- fences is YAML. Everything after the second fence is the skill body, which only loads once the skill triggers.
Field reference
name (required)
The skill's identifier.
Rules that keep names portable:
- Lowercase letters, numbers, and hyphens:
pdf-form-filler, notPDF Form Filler - Match the folder name exactly: a folder
meeting-summariser/containing a SKILL.md namedmeeting-summarizeris a mismatch waiting to cause confusion - Keep it short and specific; the name appears in skill listings and install commands
- Never rename casually: the name is how other skills, docs, and users reference it, so a rename is a breaking change
# Good
name: sql-migration-checker
# Bad: spaces and capitals
name: SQL Migration Checker
description (required)
The trigger surface. When a message arrives, Claude sees the name and description of every installed skill and decides from those alone whether to load one. Two jobs in one sentence pair: what the skill does, and when to use it.
# Weak: says what, never when
description: A skill for working with database migrations.
# Strong: what + when + the words users type
description: Reviews SQL migration files for destructive operations and missing rollbacks. Use when the user asks to check, review, or write a database migration, or mentions ALTER TABLE, DROP, or schema changes.
Practical guidance:
- Write in third person ("Reviews...", not "I review...")
- Front-load the distinctive nouns and verbs; the exact phrases users type are your keywords
- Include synonyms users actually use: "minutes", "action items", and "meeting notes" are three different triggers for the same skill
- Do not stuff it: an over-broad description makes the skill fire on unrelated prompts, which erodes trust as much as never firing
- There is a length limit on the description field; treat roughly a thousand characters as a generous ceiling and aim well under it
Getting this field right is a discipline of its own, covered in depth in how skill triggers work, and it is testable: the testing and eval guide shows how to run cold-session trigger tests against a description.
Optional metadata fields
Depending on where the skill runs, additional fields may be recognised or simply tolerated:
name: meeting-summariser
description: Summarises meeting transcripts into decisions, actions, and owners. Use when the user shares a transcript or asks for meeting notes, minutes, or action items.
version: 1.3.0
license: MIT
version: useful for release discipline even where the runtime ignores it; pairs with a CHANGELOG filelicense: worth declaring on anything you publish through the flow in publishing and sharing Claude skills- Tool or permission restriction fields exist in some environments to limit what a skill may do while active
A conservative rule: unknown-but-well-formed fields are usually ignored harmlessly; malformed YAML is not.
YAML pitfalls that break skills
| Mistake | Example | Result |
|---|---|---|
| Unquoted colon in description | description: Reviews SQL: fast checks |
YAML parse error; skill may not load |
| Tabs for indentation | invisible in most editors | Parse error |
Missing closing --- |
body merges into front-matter | Skill malformed |
| Smart quotes from a word processor | description: “Reviews...” |
Parse error or mangled text |
| Multi-line description without a block scalar | wrapped lines mid-value | Parse error |
The colon one is the most common. If your description contains a colon, quote the whole value:
description: "Reviews SQL: checks migrations for destructive operations. Use when the user mentions schema changes."
Validate before shipping. Any YAML linter works:
python -c "import yaml,sys; yaml.safe_load(open('SKILL.md').read().split('---')[1])"
What does not belong in front-matter
- Workflow steps. Instructions live in the body; the front-matter is metadata only.
- Examples and code blocks. Same reason.
- Secrets or account identifiers. The front-matter is the most-read part of the most-shared file in the folder. Placeholders like
YOUR_API_KEYonly, everywhere. - Marketing copy. "The best, most powerful summariser" contains zero trigger words. Every character of the description should earn its place as either a capability statement or a trigger cue.
A worked before-and-after
Before, a skill that never fired:
name: Helper
description: Helps with documents.
After, the same skill triggering reliably:
name: contract-clause-checker
description: Checks contracts and agreements for missing or risky clauses using a UK-focused checklist. Use when the user uploads a contract, asks to review an agreement, or mentions terms, clauses, NDAs, or liability.
Nothing in the body changed. Trigger reliability is a front-matter property, which is why it is worth a whole reference post. If the skill also participates in a multi-skill workflow, the name in this block is the identifier other skills use, as described in skill chaining.
Frequently asked questions
Does the front-matter load into context for every message?
The name and description of installed skills are visible to Claude so it can decide when to trigger them; the body loads only after triggering. This is why description quality dominates skill performance and why a bloated description imposes a small cost on every message.
Can the description span multiple lines?
Yes, using a YAML block scalar (description: >- followed by indented lines) or by quoting a long single line. Avoid raw unindented wrapping, which breaks parsing.
What happens if two installed skills have the same name?
Behaviour is environment-dependent and never good: one may shadow the other or installs may conflict. Keep names globally distinctive, especially before publishing.
About the author
Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.
Next step: Put the reference to work with writing a Claude skill from scratch, or explore 1,000+ AI tools at yanni.uk/ai-tools.
Sources
- Claude documentation (agent skills): https://docs.claude.com
- YAML specification: https://yaml.org