![\"Diagram:](\"https:\/\/pletzenauer.com\/wp-content\/uploads\/2026\/06\/en-infographic-sub-agents.png\")
What a sub-agent is<\/h2>\n\n
The main session is the orchestrator. It is the instance you talk to. It starts independent sub-agents and assigns them tasks.<\/p>\n\n
Each sub-agent works in its own fresh context. It reports back only a compact result. Sub-agents talk to the main session, never to each other.<\/p>\n\n
Why they are worth it<\/h2>\n\n
Four reasons make sub-agents useful.<\/p>\n\n
- A clean context.<\/strong> Research, long logs and large reports stay out of the main chat.<\/li>
- Parallel work.<\/strong> Many independent tasks run at the same time instead of one after another.<\/li>
- Cheaper models.<\/strong> A small model does the legwork, a strong one runs the show.<\/li>
- Honest reviews.<\/strong> A fresh agent has not been primed to agree with you.<\/li><\/ul>\n\n
Built in or built yourself<\/h2>\n\n
Claude Code ships with generic sub-agents. Alongside them you build your own, specialized ones. A sub-agent is nothing more than a Markdown file.<\/p>\n\n
At the top sits the YAML front matter: name, description, model and permitted tools. The description is the most important lever. It decides whether the agent gets matched to the task.<\/p>\n\n
A common mistake in practice is a forgotten quotation mark. The structure breaks, and the agent never starts.<\/p>\n\n
Project or global<\/h2>\n\n
Project agents live in the repository and travel with it. Global agents live in your user folder and belong to you alone.<\/p>\n\n
Rule of thumb: if the team should use it, it belongs in the project. Moving it is trivial, because it is only a file.<\/p>\n\n
When a sub-agent, and when not<\/h2>\n\n
Not every task needs a sub-agent. Too many of them often produce worse results. One simple question helps.<\/p>\n\n
Is this about to dump a mountain of information into my chat that I will never read again? If yes, delegate. If no, it stays in the main session.<\/p><\/blockquote>\n\n
Use sub-agents when a lot of files have to be read, when jobs can run in parallel, or when you want an unbiased review.<\/p>\n\n
Skip them for small edits, for steps that depend on one another, or when the agent would need to ask you a question.<\/p>\n\n
Dynamic workflows and \u201cultra code\u201d<\/h2>\n\n
Since Opus 4.8 there are dynamic workflows. The main session then starts many sub-agents in parallel on its own. That is powerful, but it burns through your session limit fast.<\/p>\n\n
That is why the trigger word was changed from \u201cworkflow\u201d to \u201cultra code\u201d. No large workflow now starts by accident. Reach for the tool deliberately.<\/p>\n\n
Take permissions seriously<\/h2>\n\n
If an agent can read or change data, you have to assume it will do so at some point. So grant only the tools it genuinely needs.<\/p>\n\n
For research and review agents that usually means read-only. With agent files from other people, check for possible prompt injection first.<\/p>\n\n
My promise to you<\/h2>\n\n
Sub-agents are not an end in themselves. They are a tool for dividing up work. The gain is less noise in the chat, lower cost and an unbiased look at your work.<\/p>\n\n
My promise to you: I recommend sub-agents only where they measurably help.<\/p>\n\n
- Parallel work.<\/strong> Many independent tasks run at the same time instead of one after another.<\/li>