YAML Front Matter Design

The YAML front matter is the first layer of the 3-layer skill system, and it is the most critical. It is always loaded into the system prompt — every session, every time, regardless of whether the skill is invoked. This means it consumes tokens whether you use the skill or not. That constraint forces a discipline: the front matter must be small, precise, and purposeful. Anthropic recommends keeping it under 1,000 characters. In practice, the best front matter sections are 400-600 characters.

The front matter serves exactly one function: it tells Claude whether to investigate this skill further. Think of it as a business card. When Claude reads a user prompt, it scans the front matter of every installed skill looking for a match. If the front matter is vague — "helps with projects" — Claude cannot determine relevance and will either always activate the skill (wasting tokens) or never activate it (making the skill useless). If the front matter is precise — "Transforms CSV files into normalized database import formats. Invoke when user says clean the data, fix the CSV, or normalize the spreadsheet" — Claude knows exactly when to load the full skill.

The anatomy of effective front matter has four components. First: a name field that is concise and descriptive. "csv-normalizer" not "data-processor." Second: a description field that answers what this skill does and when it should be invoked — in a single sentence. Third: trigger words — the explicit phrases that should cause Claude to load this skill. Include three to five phrases, covering both formal ("normalize the dataset") and informal ("clean up this CSV") variations. Fourth: an optional scope field that specifies file types, directories, or contexts where the skill applies.

The trigger words are the make-or-break element. Claude uses them as pattern-matching anchors. If a user says "clean my data" and your trigger list includes "clean the data," Claude will match. If your trigger list only includes "normalize CSV files," Claude will miss the intent. Cover the vocabulary your team actually uses, not the vocabulary you wish they used.