# Keeping SKILL.md Short and Details in References — Claude Code Skills & SKILL.md

Source: https://www.geekswithgeeks.com/en/claude-code-skills/f-size

> Split long skills so the common path stays cheap.

## 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.

```python
# 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.

**Quiz:** What belongs in a reference file rather than SKILL.md?

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

*Answer:* Long, rarely needed detail such as full API docs or schemas. Keep the common path in SKILL.md and push rare detail out.