Skills and subagents: the agent reuse pattern
Table of contents
Two agent design patterns consolidated in 2025-2026: skills and subagents. Together they form the most effective recipe for building complex agents without the orchestrator’s context becoming an uncontrollable monster.
Key takeaways
-
A skill is a self-contained package with instructions, tools, and examples; the agent loads only those relevant to the task.
-
A subagent is a fresh agent that receives a bounded task, executes in isolation, and returns a synthesised result.
-
The full pattern: orchestrator + skills (capabilities) + subagents (isolated execution).
-
A skill must fit in your head; if it needs more than a paragraph of documentation, it’s probably two skills.
-
Subagents must return synthesis, not transcript; if the orchestrator reads everything, the isolation is lost.
Skills: reusable capabilities
A skill is a self-contained package with:
-
Specific instructions.
-
Associated tools.
-
Usage examples.
Example skills:
-
"Draft an incident communication".
-
"Review TypeScript code per our conventions".
-
"Prepare release notes from commits".
The agent loads only skills relevant to the task, keeping its context small and behaviour predictable.
The operational benefit is huge: a well-made skill is reused across projects, versioned, tested. The antipattern is a single giant prompt trying to cover every capability, inflated context, unpredictable behaviour, unmaintainable.
Subagents: context isolation
A subagent is a fresh agent that:
-
Receives a bounded task.
-
Executes in its own context.
-
Returns a compressed result.
The orchestrator delegates; the subagent works in isolation; the result comes back synthesised.
Typical cases:
-
Code exploration: "find every use of this function and report".
-
Review: "validate these changes against X criteria".
-
Generation: "produce a first version of this document".
The orchestrator doesn’t need to read the whole exploration, just the subagent’s summary.
Composition: orchestrator + skills + subagents
The full pattern:
-
Orchestrator: coordinates work and maintains the task’s global context.
-
Skills: define reusable capabilities the orchestrator can load.
-
Subagents: execute isolated work without polluting the orchestrator’s context.
Typical 2026 stack:
-
Claude Code[1] with its native skills and subagents system.
-
Homegrown implementations using MCP + custom coordination logic.
-
Frameworks like LangGraph[2] or AutoGen[3] formalising the pattern.
Best practices
Three rules that recur in successful implementations:
-
A skill must fit in your head: if it needs more than a paragraph of documentation, it’s probably two skills.
-
Subagents must return synthesis, not transcript: if the orchestrator reads everything the subagent did, you lose the isolation that justifies the pattern.
-
Subagent results are versioned by hash: same input, reuse output instead of repeating work.
Conclusion
Skills and subagents are the shape complex-agent composition takes in 2026. Teams internalising the pattern build maintainable, reusable systems; those continuing with monolithic prompts accumulate debt that slows all future work. Adopting the pattern is one of the few levers separating amateur from professional implementations in agentic engineering.
Frequently asked questions
How do I know a skill is too big and should be split?
The rule is that a skill must fit in your head: if it needs more than a paragraph of documentation, it is probably two skills. A skill is a self-contained package with specific instructions, associated tools and usage examples, and the agent loads only those relevant to the task to keep its context small and its behaviour predictable. The antipattern is a single giant prompt trying to cover every capability: inflated context and unmaintainable.
What should a subagent return to the orchestrator?
Synthesis, not transcript: a subagent is a fresh agent that receives a bounded task, executes it in its own context and returns a compressed result. If the orchestrator reads everything the subagent did, you lose the isolation that justifies the pattern. Typical cases are code exploration, validating changes against given criteria and producing a first version of a document. Results are versioned by hash so the same input reuses the output instead of repeating work.
