SKILL.md frontmatter, field by field
A skill file opens with a YAML block between two lines of three dashes. Two fields are required, name and description. The rest are optional, and a key the loader does not recognise is usually ignored rather than rejected. That last part matters: a misspelled optional field fails quietly, so the setting you thought you applied is simply absent.
The two required fields
name
The identifier. Keep it lowercase and hyphenated, and keep it identical to the folder the file sits in. A name that disagrees with its directory is the classic silent failure, because the loader looks for the pair and finds neither half on its own.
description
The only text read before the skill is chosen. It should say what the skill does and when to reach for it. Writing a good one is its own subject, covered in how to write a description that gets picked.
The optional fields worth knowing
allowed-tools
Limits what the skill may use once it loads. Give it a list, or a single tool name. A file that only reads and rewrites text does not need shell access, and narrowing it is the one frontmatter field with a real safety payoff. Omit it and the skill inherits whatever the session already allows, which is usually everything.
argument-hint
A usage string shown when the skill is invoked directly by name, for example [--mode <mode>] [path]. It documents the arguments; it does not parse or enforce them. Treat it as a prompt for the human, not a schema.
license and version
Metadata for anyone redistributing the file. license takes a short identifier such as MIT, or a pointer to a full terms file. version is a plain string, so nothing stops it drifting out of date, and nothing warns you when it does.
metadata
A free-form map for your own tooling: owner, last review date, an internal ticket. Nothing in the loader reads it, which is exactly why it is useful for the things your team needs to track and the loader should ignore.
A complete block
---
name: invoice-chase
description: Draft a follow-up email for an overdue invoice, with the
amount, the age of the debt, and a clear next step. Use when the user
mentions an unpaid invoice, a late payment, a client who has not paid,
or asks to chase billing. For new invoices, use the billing skill.
allowed-tools:
- Read
- Write
license: MIT
version: 1.2.0
argument-hint: "[client] [invoice-id]"
metadata:
owner: finance
last_reviewed: 2026-08-23
---Everything after the closing dashes is the instruction body, in ordinary markdown.
Three mistakes that look like something else
Unquoted colons.
A description containing a colon, such as Handles one thing: invoices, breaks the YAML parse and takes the whole file down with it. Quote any value with a colon in it, or reword around it.
Tabs for indentation.
YAML rejects tabs. An editor that converts spaces to tabs on save produces a file that was valid an hour ago and is not now, with no change you can see in the diff.
A stray key that seems to work.
triggers: and homepage: turn up in real skill files. They are harmless, and they are also inert. If you add a field expecting behaviour from it, confirm the behaviour rather than the absence of an error message.
Works with Claude Code.
Check your frontmatter now
Paste a skill file into the free checker. It parses the block, names any field that is required, misspelled, or inert, and then runs the file against realistic prompts to see whether it would actually be picked. No account needed.
Check a skill file