What you're actually writing when you write a SKILL.md
This article shows that SKILL.md files aren’t static prompts but loader specifications defining what to load, when, and at what cost. It breaks down the three progressive-disclosure levels, explains how architecture—not instruction content—drives context consumption, and highlights common antipatterns that bloat or break skills.
- A 1,200-line monolithic SKILL.md ate 20% of the context window every turn; splitting it into a 180-line driver plus reference files and a script dropped that to 7%.
- SKILL.md files are loader specs with three tiers—frontmatter (~100 tokens, always loaded), body (loads on invocation, keep under 500 lines), and references/scripts (loaded or run only on demand).
- Adding YAML frontmatter to reference files accidentally promotes them to always-loaded skills, cluttering the skill list and causing out-of-context invocations—removing it fixed silent routing errors.
- Context consumption is driven by how content is architected across these layers, not by how much instructional detail is written.
Writing a SKILL.md isn’t about crafting a giant prompt for your agent. It’s defining how tooling loads your content in three stages—frontmatter (Level 1), body (Level 2), and references or scripts (Level 3)—so you only pay for what’s needed, when it’s needed. Frontmatter, pulled into the system prompt every turn, holds the skill name and a brief description (about 100 tokens). Level 2, the procedural instructions in SKILL.md, loads only on invocation—Anthropic recommends keeping this under 500 lines. Level 3 contains external markdown or executable scripts, fetched on demand or run for output; these don’t bloat your context window.
Failing to follow this progressive‐disclosure model leads to hidden costs and weird failures. A 1,200-line monolithic SKILL.md consumed 20 percent of the context window every turn; splitting it into a 180-line driver file plus three reference files and a helper script cut that down to 7 percent. Another gotcha: adding YAML frontmatter to reference files promotes them to always-loaded skills, cluttering the “pinboard” of available skills and causing the agent to invoke them out of context. Removing that frontmatter fixed silent routing errors.
Think of your agent’s context window like a busy kitchen. The pinboard lists recipe titles and summaries—the frontmatter. You pull down only the recipe card you need when an order comes in—that’s Level 2. If the recipe points to a sauce guide or a stand mixer, you fetch that chapter or run the script at that moment—Level 3. Violating this setup—by dumping everything into the pinboard or loading all recipes up front—leads to context drift, high latency, and hallucinations. Keeping each layer lean, and structuring content around when it’s actually consumed, is where the real efficiency gains emerge.