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.