Español

Past 700 Lines, Split the Skill

Your 800-line AI doc isn't being read. It's being skimmed.

A skill file is only useful if the model actually loads and follows it. Past roughly 700 lines — or the moment it starts covering multiple unrelated topics — a skill stops being read carefully. It gets skimmed, key rules get missed, and it eats a huge slice of context whether the current task needs all of it or not. The fix is progressive disclosure: split the giant file into focused pieces, and do it without breaking a single existing reference.

Why big skills stop working

Two failure modes compound past the threshold:

• Skim instead of read. Long, multi-topic files dilute attention. The rule that mattered for this task is buried on line 640, next to four topics that don't apply.
• All-or-nothing loading. A monolith loads whole. You pay full context cost even when the task touches one section, crowding out the code and reasoning that actually need the window.

The signal to split is simple: about 700 lines, or more than one topic in one file.

The mechanism: split without breaking references

The trick is to split so that every existing link, mention, and @-reference to the old file still resolves.

1. Keep the original filename as an overview entry. Don't delete or rename it. Convert its contents into a short overview plus a one-level-deep table of contents pointing at the new pieces. Every reference that already targets this filename keeps working — it now lands on a map instead of a monolith.
2. Move each topic into a flat sibling file in the same category. Not nested subfolders — flat siblings, one focused methodology each.
3. Link one level deep only: entry to sibling, never sibling to sibling. The overview points at the siblings; the siblings don't cross-reference each other. That keeps the load graph shallow and predictable.

# Before: one monolith
skills/release.md            # 800 lines, five topics

# After: overview entry + flat siblings
skills/release.md            # SAME filename — now an overview + TOC
skills/release-versioning.md
skills/release-changelog.md
skills/release-rollback.md
skills/release-announcements.md

<!-- skills/release.md — overview entry, references one level deep -->
# Release methodology (overview)
Load the sibling that matches your task:

- Versioning & tagging → release-versioning.md
- Changelog generation → release-changelog.md
- Rollback procedure   → release-rollback.md
- Release announcements → release-announcements.md

Why this shape holds up

Each sibling stays focused and loadable on its own, and the preserved entry filename means nothing upstream breaks.

Power moves

• Split on topic, not just on line count. Two unrelated concerns in one file is reason enough, even under 700 lines.
• Never rename the entry. The whole no-broken-references property depends on keeping the original filename as the overview.
• Keep the graph one level deep. Entry points at siblings; siblings don't point at each other. Deeper graphs make loading unpredictable.
• One methodology per sibling. If a sibling itself starts sprawling past the threshold, split it the same way.
• Re-audit after splitting. New sibling files start life unreferenced by anything but their parent — note that so a later audit doesn't flag them as dead.

Resources

• Agent Skills — Anthropic docs (progressive disclosure)
• Effective context engineering for AI agents — Anthropic
• Memory / CLAUDE.md imports — Claude Code docs
• Model Context Protocol — resources