When to split a large skill into two, and when not to
A skill that does two jobs triggers vaguely and loads rules for both on every use. How to tell when a skill has become two, and how to split it without overlap.
Skills grow. A design skill picks up rules for writing copy; a review skill starts generating fixes. At some point one skill is two jobs sharing a folder, and both jobs get worse.
Signs it has become two skills
- The description needs "and" to say what it does.
- The rules fall into two groups that never apply to the same request.
- A request for one job loads rules written for the other.
When not to split
If the rules are one system, split the reference files, not the skill. A design system is one job even when it has tokens, components and motion rules; those are three files in references/, as in the references folder.
How to split cleanly
- Write each new description around the nouns only its job uses.
- Move each group of rules to its own
SKILL.md; share nothing implicitly. - State the boundary in one line where the two jobs meet.
- Test near-misses between them, as in two skills wanting the same prompt.
Questions
How do I know a skill should be split?
Its description needs 'and' to explain what it does, its rules divide into two groups that never apply together, and requests for one half trigger rules meant for the other.
Is it better to have many small skills?
Not automatically. Every installed skill adds its description to what Claude considers. Split along real job boundaries, not to make files small.
How do I stop the two new skills overlapping?
Give each description the nouns only its job uses, and say in one line which owns the shared edge. Then test near-misses between them.