Skills that compose

A skill's body is just instructions Claude follows. That's it. There's no special "skill runtime" with limited capabilities. If a human with the same instructions could read another recipe, dispatch a helper, or run a shell command — so can Claude.

Which means a SKILL.md can say:

• "Read the /foo skill and apply its workflow to the user's input."
• "Dispatch a general-purpose agent with this prompt template, filled in with the user's data."
• "Call Bash to run the build, then Read the log file and report failures."

None of that requires a special API. It's just text. Claude is reading the markdown and acting on it, the same way it reads anything else.

Two flavours, both fine:

Your SKILL.md says: "Invoke the verify skill on the change you just made." Claude calls the Skill tool with name verify. That skill runs, returns, control comes back to yours.

Your SKILL.md says: "Read ~/.claude/skills/foo/SKILL.md and apply its workflow to the user's input." Claude reads the file with the Read tool and follows the instructions. No special invocation — the second skill's body just becomes part of Claude's working context.

Use direct invocation when the second skill is well-tested and you want its triggering / completion contract. Use read-and-follow when you want only some of its logic, or when you want to tweak the inputs.

This is the most common composition pattern by far. Your skill says: "for each chapter, dispatch a general-purpose Opus agent with this template, filled in with the chapter's content."

book-builder does exactly this. Its Path B (multi-chapter) workflow scaffolds the shell file once, then fires off N parallel agents — one per chapter — each editing the same file at a different anchor. Three lines in the SKILL.md, hours of parallel work.

Why agents instead of doing it inline? Two reasons:

• Parallelism. The parent skill can dispatch ten agents at once. Doing the same ten tasks sequentially would take ten times longer.
• Context isolation. Each agent gets its own fresh context window. The parent doesn't drown in token noise from work it doesn't need to read.

An orchestrator is a thin skill that doesn't do work itself; it coordinates. Its body is mostly: pick the right path, fill in a template, dispatch the right agents, verify the result.

book-builder/SKILL.md is about 250 lines of instructions and references. None of those lines build a chapter. The actual chapter-building happens in agent-built HTML files, each agent invoked from a single instruction in the orchestrator. The orchestrator's job: pick paths, fill templates, dispatch, verify. That's it.

Some signs you're looking at an orchestrator:

• Most of the body is "now dispatch an agent" or "now invoke skill X".
• The skill references other files (templates, references) more than it includes them.
• Removing the skill doesn't lose any underlying capability — it loses only the coordination.

Two real shapes. The orchestrator delegates; the flat skill does its own work. Both are valid — the question is whether the work decomposes naturally.

Four ways composition goes wrong. Memorise these — every one of them will tempt you at some point.

• Recursive triggers. Skill A's body says "invoke skill B". Skill B's body says "invoke skill A". They share trigger phrases. Now any trigger fires both — and each invokes the other — and you have an infinite loop until the context fills up and Claude crashes out.
• Chains too deep. A calls B calls C calls D. Each link is fine in isolation, but the whole chain is opaque — failures bubble up with no clear cause. Three levels is a good practical max.
• Shared mutable state. Skills can't share variables. They can't reach into each other's memory. If skill A computes a value and skill B needs it, A has to pass it via the prompt to B or write it to a file B reads. Don't pretend otherwise.
• Hidden orchestrators. Your "data extraction" skill is secretly an orchestrator that dispatches five agents to do unrelated things. Now no one — not even you in three months — can predict what it does from its name. Be honest about coordination. Name the skill what it is.

There is no shared global state. Repeat: there is no shared global state. Skills do not have variables they can pass around. Agents do not see what their parent saw — they see only what their prompt contains.

So how do skills share context? Three honest channels:

• The prompts they generate for sub-agents. Most common. Whatever the sub-agent needs to know, put it in the prompt. Be explicit; be complete.
• Files they write that sub-agents read. For larger payloads — outlines, scaffolds, datasets — write a file and tell the sub-agent which path to read.
• Command-line args for shell helpers, when one part of the workflow calls a script another part also uses.

The agent receives only what its prompt contains. Test that. If you find yourself thinking "well, the agent knows that already" — it doesn't. Pass everything explicitly or it isn't passed.

Sometimes one flat skill is the right answer. Composition is for when:

• The sub-task is genuinely independent — would still make sense as its own skill standalone.
• Parallelism helps — you have N things to do in parallel, and dispatching N agents beats doing them in sequence.
• The sub-skill already exists and is well-tested. Compose to reuse, not to invent.

Don't compose for elegance. Don't compose because "it feels more modular". A flat skill that fits on one screen and works is better than a beautifully-decomposed three-level call graph that has a recursion bug.

You'll see the same four shapes over and over. Tap a card to see a concrete example.