How long should SKILL.md be?
SKILL.md is loaded whenever the skill is in use, so every line costs context. A practical length, what to keep in it, and what to move to references.
When a skill is in use, its whole SKILL.md body sits in context. A long one crowds out the work you asked for. The question is not how long it may be, but how short it can be while still steering Claude correctly.
What earns a place
- The rules Claude gets wrong without being told, stated so they can be checked.
- A short workflow, if order matters.
- A map of reference files and when each is needed.
- What the skill deliberately does not do.
What should move out
- Full token lists, tables of values, long examples.
- API notes and edge cases that apply to one task in ten.
- Anything Claude could look up in a file when the task calls for it.
Our design skills keep SKILL.md to the rules and a workflow, and put tokens and component code in references/. The pattern is in the references folder, and how to measure the cost is in what a skill costs you in context.
Questions
Is there a maximum length for SKILL.md?
Anthropic's guidance for skills suggests keeping the body comfortably short, in the low hundreds of lines at most, and moving detail into separate files that are read when needed.
What must stay in SKILL.md?
The frontmatter, the rules Claude must follow every time, and pointers to the reference files with when to open each.
Does a longer SKILL.md make the skill trigger better?
No. Triggering is decided by the description in the frontmatter. Length in the body only changes how much context the skill uses once active.