Orchestrating work with Claude Code: skills, routing and subagents

A single agent with a long prompt and every tool available is the default, and it degrades in a predictable way. The instructions get longer, they start contradicting each other, and behaviour becomes a function of what happened to be nearest the end of the context.

The fix is structure: work gets routed to something scoped, and repeatable work is encoded once rather than re-explained every time.

Skills: encode the playbook once

A skill is a procedure written down - the steps, the rules, the failure modes - that gets loaded when it is relevant rather than living permanently in the prompt.

The distinction that matters: a skill is not a description of a capability, it is a procedure with the judgement included. “Handles deployments” is useless. A skill that says which environment to check first, what the rollback command is, and which failures mean stop rather than retry is a colleague’s knowledge in a file.

Good candidates are tasks you have explained more than twice, tasks with a non-obvious correct order, and tasks where getting it wrong is expensive. If you find yourself correcting the same mistake across sessions, that correction belongs in a skill.

Keep each one narrow. A skill covering “content” that tries to handle blog posts, newsletters and social copy will be mediocre at all three. Three skills with clear triggers beat one with a decision tree.

Routing: decide before you act

Routing is the step that gets skipped, and skipping it is why agents charge into the wrong approach confidently.

The useful move is to classify the task before doing anything: is this a one-line fix, a multi-step build, an unclear requirement, or a bug? Each answer implies a different path. An unclear requirement needs clarification first, not code. A bug needs a reproduction before a fix. A one-liner needs neither.

Encode this as an explicit early step rather than hoping it emerges. The cost of classifying wrong is small; the cost of not classifying is an hour spent building the wrong thing well.

Subagents: buy context isolation

A subagent is a fresh context that does a scoped job and returns a conclusion. You are buying one thing: isolation. The subagent reads twenty files and returns three paragraphs, and the nineteen thousand tokens it burned never touch the parent context.

That makes them right for:

• Broad search where you want the answer, not the file dumps.
• Independent work that can genuinely run in parallel.
• Anything that would otherwise flood the main context with noise.

And wrong for:

• A single known lookup. Spawning a whole context to read one file you can already name is pure overhead.
• Work needing full conversation history. The subagent does not have it, and summarising it into the prompt usually costs more than doing the work directly.
• Sequential steps with tight coupling. Each handoff loses detail.

The honest heuristic: if you can name the file, read it. If you would have to go looking, delegate.

Verify, do not assume

The most expensive failure in an orchestrated system is a step that reports success without checking. It propagates - every later step builds on a foundation that was never confirmed.

Every skill should end with a verification step that actually runs something: the test suite, the build, a query against the real state. “I updated the config” is a claim. “I updated the config and the build passes” is a fact.

This matters more with agents than with people, because an agent will state completion with total confidence either way. Confidence carries no signal, so the check has to be mechanical.

Let it fail loudly

Resist the urge to make agents resilient by having them work around problems. An agent that silently falls back to a different approach when the first fails produces work you cannot reason about, and hides the failure until it surfaces somewhere expensive.

Fail fast, say what failed, stop. A stopped agent with a clear error costs a few minutes. An agent that quietly took a different path costs however long it takes to notice.

What to read next

• Agent memory - what persists between all of this.
• Approval gates - where an orchestrated system has to stop and wait.
• The Agent OS - how routing, roles, skills and memory fit together in one running system.
• Claude Code documentation - the tool itself.