What actually goes into a SKILL.md

SKILL.md is not a long prompt but a loader specification that designs runtime behavior. This format, released by Anthropic in December 2025, works uniformly across Claude Code, Kiro, Cursor, Codex CLI, and others, and even the same instructions can differ in cost and performance depending on where they are placed.

When a single 1,200-line SKILL.md was restructured into a 180-line body, 3 reference files, and 1 helper script, context occupancy dropped from 20% to 7%. The results differed even with the same model and the same task, and the performance difference came not from the wording but from where things were placed.

The runtime operates on progressive disclosure.

• Level 1: The frontmatter containing name and description is loaded every turn and serves as a routing signal.
• Level 2: The body of SKILL.md is only read when the skill is judged to be needed, and Anthropic sets roughly 500 lines as the recommended upper limit.
• Level 3: references/ and scripts/ are only read or executed when needed, and only their output enters the context.

The kitchen analogy is the most accurate. The note on the wall is the frontmatter, the recipe you take out is the body, a specific page in the binder is the reference, and the mixer is the script. If this structure is followed, a skill waits at almost no cost and uses memory only when needed; if it's violated, it quietly breaks down due to environment drift and version sensitivity. A setup that worked well on one model can also become unstable after an upgrade.

There are two representative pitfalls.

• Adding frontmatter to a reference file so it gets exposed like a top-level skill and gets triggered directly without context.
• Cramming all instructions into a single SKILL.md, turning it into a 1,200-line lump.

Ultimately, the core of writing SKILL.md is not prose skill but architecture.