Skill Load Tips

Refactor pattern for SKILL.md files where the body is the only thing the agent ever reads. The references/ folder might as well not exist.

The Failure Mode

Large skills frequently ship with rich reference files (references/*.md) that contain the load-bearing detail — full ARIA patterns, banned-vocab lists, before/after examples, archetypes — and a SKILL.md body that summarizes them. The agent reads the body, feels it has "enough," and never fans out. The reference files become dead weight.

This is the inline-substitutes-for-reference antipattern. It is the single most common reason a well-organized skill underperforms.

Symptoms (how to spot it)

A SKILL.md likely has this problem if two or more apply:

• Body is over 250 lines and inlines checklists, tables, or banned-word lists that also live in a referenced file.
• The "Reference Index" / "Files" section is at the bottom, after the operating loop.
• References are introduced with hedged phrases: "For depth, read X", "see X for details", "X has more".
• No upfront "router" mapping task → mandatory file.
• Reference files are linked from other reference files (deep nesting), not directly from SKILL.md.
• Reference files over 100 lines have no table of contents at the top.