Keeping SKILL.md Short and Details in References

The body is paid for every time

Every time a skill triggers, its whole body enters the context, so a long body is a recurring cost and buries the key steps. A common guideline is to keep SKILL.md under about 500 lines, with the main path first and rarely needed detail moved into reference files. Good candidates for separate files: long API documentation, large examples, edge-case handling, database schemas, per-language or per-framework variants (so a Python project does not load the Java notes), and anything only needed in a specific situation. A helpful test: if removing a paragraph would not change what Claude does in the typical run, it belongs in a reference file loaded on demand. Split by topic (what the reader needs), not by arbitrary size.

What loads when, run

I ran this with plain Python 3 (standard library only). A 180-line SKILL.md with three reference or template files totalling 1,290 lines: only the 180 lines load when the skill triggers; the other 1,290 lines are read only if the task needs them. The line counts are illustrative.

# Keep SKILL.md focused: long procedures and big reference material belong in separate files loaded on demand.
files = {"SKILL.md": 180, "references/api.md": 900, "references/errors.md": 350, "templates/report.md": 40}
body_limit = 500
for name, lines in files.items():
    flag = "" if name != "SKILL.md" or lines <= body_limit else "  <-- too long, split it"
    print(f"{name:24} {lines:5d} lines{flag}")
print("loaded when the skill triggers :", files["SKILL.md"], "lines (SKILL.md)")
print("loaded only if the task needs it:", sum(v for k, v in files.items() if k != "SKILL.md"), "lines (references/templates)")

Output:

SKILL.md                   180 lines
references/api.md          900 lines
references/errors.md       350 lines
templates/report.md         40 lines
loaded when the skill triggers : 180 lines (SKILL.md)
loaded only if the task needs it: 1290 lines (references/templates)

Add a table of contents to long references

A short index at the top of a long file helps Claude jump to the right section.

Quick check: What belongs in a reference file rather than SKILL.md?

• The main steps every run needs
• The skill's name and description
• Long, rarely needed detail such as full API docs or schemas
• Nothing