YAML Frontmatter

What is YAML Frontmatter, and how does it differ from regular file content?

YAML frontmatter is a standalone Block at the very top of a Markdown file, wrapped between a pair of --- markers, containing metadata about the file — name, description, version, license, and so on — written in YAML format. The difference from the file's main body is this: the body is substantive content meant to be read and understood by a reader (or Claude), while frontmatter is a structured label describing "what this content is," and it's usually not shown directly to users — instead it's used by the system for indexing, filtering, or deciding whether to load the file at all.

In a Claude Code Skill file, frontmatter is only parsed correctly if the opening --- is literally the file's first line; if any other text comes before it, the entire file is treated as having no frontmatter, and all of its content gets handled as ordinary documentation instead.

Why does YAML Frontmatter exist, and what problem does it solve?

Without frontmatter, the only way for a system to determine what a file "is" would be to read the entire content and analyze it — tolerable with a handful of files, but when a system might have dozens of Skills installed at once, reading every Skill's full content on every startup just to judge relevance burns through a large amount of unnecessary context.

This is exactly what frontmatter solves: it condenses "what this is and when to use it" into a few dozen tokens of metadata, so the system only needs to read that small Block at startup to make an initial judgment, and only loads the full body when a Skill is actually needed. This is the first layer of what the Skill architecture calls three-layer Progressive Disclosure — metadata always loads, the body loads on trigger, and extension files load only when actually needed.

What does YAML Frontmatter actually look like in practice?

Under the Claude Code Skill standard, only six fields are officially recognized in frontmatter: the required name (lowercase, hyphen-separated) and description (explaining what the Skill does and when to use it), plus the optional license, compatibility, metadata, and allowed-tools. When Claude Code starts up, it only reads each Skill's name and description — a step that costs an extremely small number of tokens, so even having many Skills installed at once doesn't create a noticeable burden.

Worth noting: the description field matters far more than any other. It's the only thing the system matches against when deciding whether to trigger a given Skill — if it isn't specific enough, Claude may never trigger the Skill even with a perfectly complete body, simply because it can't judge the relevance. This is also why most authoring guides emphasize the same point: what's most worth polishing in frontmatter usually isn't the number of fields, it's how precisely that one description line is written.

Understanding how YAML Frontmatter works — how does this actually affect how I write a Skill?

The most direct effect is on the order you write things in: get description right first — specific enough that Claude can tell at a glance whether a given request should trigger it — before thinking about what goes in the body, not the other way around. Many newcomers spend their effort on making the body as detailed as possible while overlooking that if description doesn't judge accurately, Claude never even gets to the step of reading the body — no matter how well-written it is, it never gets a chance to matter.

Another practical pitfall is getting the position of that opening --- marker wrong — an extra blank line or comment before it, for instance, causes frontmatter parsing to fail and the whole file gets treated as plain content. In this case the Skill usually doesn't throw an obvious error, it just quietly fails to work (no recognized name). After writing a Skill, it's worth actually testing whether Claude triggers it in the right situation, rather than just eyeballing the formatting.