Once you have more than one Skill, the interesting questions stop being about any single file. They become about boundaries: what is one Skill and what is two, what gets bundled, and what happens when several could fire at once.
Last in a series on Agent Skills.
Pattern 1 — the hub and its references
The most common shape for a substantial Skill: a lean SKILL.md that describes the workflow, and a references/ directory holding the detail.
automation-recommender/
├── SKILL.md (the decision procedure)
└── references/
├── hooks-patterns.md
├── mcp-servers.md
├── plugins-reference.md
├── skills-reference.md
└── subagent-templates.mdFive reference files, roughly 32KB between them. A request about hooks opens one 6KB file; the 8KB one about MCP servers is never touched. This is progressive disclosure used deliberately rather than accidentally.
Use it when the Skill has one workflow but several deep subjects.
Pattern 2 — the verb split
Several official plugins ship paired Skills with the same subject and different verbs — one to configure a service, one to access it. Setting up a Slack connection and reading messages from it are different tasks, done at different times, by people in different moods.
Split when the trigger conditions genuinely differ. Keeping them together produces a description that has to say “use when setting up or using”, which matches everything and therefore discriminates nothing.
Pattern 3 — orchestrator plus code
Covered in the previous article, but it is a composition pattern too: the SKILL.md holds the judgement and the sequence, and bundled scripts hold every step with a single correct answer. The Skill becomes a thin, readable procedure over a tested library.
Pattern 4 — the plugin bundle
Related Skills that share a domain can be distributed together as a plugin, versioned as a unit. This is how a team ships a house style: the review Skill, the implementation Skill and the release Skill arrive together and stay in step.
The practical benefit is not technical. It is that one person maintains the set and everyone else gets the update.
Where composition actually goes wrong
The everything Skill. One Skill that handles the whole domain, with a description listing eight unrelated triggers. It fires constantly, including when it should not, and drags its entire body into context each time. Split it.
Overlapping neighbours. Two Skills whose descriptions do not mark a boundary. Each should say what it is not for when a sibling exists.
The reference nobody reads. A bundled file that SKILL.md never mentions is dead weight — it costs nothing in tokens, which is exactly why it rots unnoticed. If the body does not point at a file, delete it.
Instructions that should be code. A long prose description of an algorithm is a script that has not been written yet. It will be re-derived, slightly differently, on every run.
Before you distribute anything
Two constraints worth planning around rather than discovering. Skills do not sync across surfaces — the coding agent, the API and the chat app each need their own copy, with different sharing models: personal, workspace-wide and per-user respectively. And a Skill is executable capability, so treat installing a third-party one as you would treat adding a dependency: read the scripts, look for network calls that do not match the stated purpose, and be especially careful anywhere it will touch production data.
What to take away
Boundaries are the whole design. One Skill per trigger condition, detail pushed into references, determinism pushed into scripts, related Skills shipped as a set. Get those right and the individual files are easy — most of a good Skill is one page of clear instructions and a description written for the person who does not know it exists.
Earlier in this series: what a Skill is, the three loading levels, writing a description that triggers, and shipping scripts that cost no context.