Keeping the Main File Lean, Reference Files Deep

Claude Code Skills·Intermediate·6 min read·Sep 6, 2026

A pattern for skills that outgrow one page: a short main file that points to deeper reference files, loaded only when actually needed.

The recipe card that points to page twelve

A good recipe card doesn't try to fit an entire cookbook onto one index card. If a dish needs a complicated sauce, the card often just says "for the sauce, see page 12" instead of cramming the sauce recipe into the margins. Most of the time, page 12 never gets opened, because most dishes don't need that sauce. But it's there, ready, for the times they do.

A well-built skill uses the same trick once it outgrows a single page.

Splitting a skill into a short front door and deeper rooms

review-checklist/
  SKILL.md              (short: what this is, when to use it, the basics)
  references/
    security.md          (only opened for security-sensitive changes)
    database-migrations.md (only opened when a migration is involved)

The main SKILL.md stays short enough to read in a few seconds and covers the common case completely on its own. The references/ files hold the deeper, less-frequently-needed material, and the main file simply tells Claude when to go open one: "if this change touches a database migration, also read references/database-migrations.md."

Everything in one long file

Slower to scan even for the common case, and most of the content goes unused most of the time.

Short main file plus reference files

The common case stays fast, and depth is available exactly when a specific situation actually calls for it, not before.

Why this isn't just tidiness

This split isn't only about readability for a person skimming the file. It changes what actually gets loaded into a conversation. A short main file that only pulls in a reference file when a specific condition is met means most tasks handled by this skill only ever load the small, fast part. The heavier material stays out of the way until the one situation that actually needs it shows up, the same restraint that made the whole idea of a skill worthwhile back in the first chapter.

A rule of thumb for when to split

If a skill's main file is still short enough to read in under a minute and covers the situations that come up 90% of the time, it's probably fine as one file. Once it's accumulated several long, only-sometimes-relevant sections, especially ones tied to specific edge cases, that's usually the signal to split them out into their own reference files.

Find the split point in something you'd write

Think back to the skill-shaped task from the first chapter. Which part of it applies almost every time, and which part only applies in a specific, less common situation? The first part belongs in a short main file. The second part is a reference file candidate.