![\"Diagram:](\"https:\/\/pletzenauer.com\/wp-content\/uploads\/2026\/06\/infographic-sub-agents.png\")
What a Sub-Agent is<\/h2>\n\n\n\n
The main session is the orchestrator. That is the instance you talk to. It starts independent Sub-Agents and assigns tasks to them.<\/p>\n\n\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\n\n
Why they are worth it<\/h2>\n\n\n\n
Four reasons make Sub-Agents useful.<\/p>\n\n\n\n
- 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 stays in charge.<\/li>
- Honest reviews.<\/strong> A fresh agent is not conditioned to agree with you.<\/li><\/ul>\n\n\n\n
Built in or self-built<\/h2>\n\n\n\n
Claude Code ships with generic Sub-Agents. Alongside them you build your own, specialised agents. A Sub-Agent is nothing more than a Markdown file.<\/p>\n\n\n\n
At the top sits the YAML frontmatter: name, description, model and allowed tools. The description is the most important lever. It decides whether the agent fits the task.<\/p>\n\n\n\n
A common mistake in practice is a forgotten quotation mark. Then the structure breaks, and the agent never starts.<\/p>\n\n\n\n
Project or global<\/h2>\n\n\n\n
Project-scoped agents live in the repo and travel with it. Global agents live in your user folder and belong only to you.<\/p>\n\n\n\n
Rule of thumb: if the team should use it, it belongs in the project. Moving it is trivial, because it is just one file.<\/p>\n\n\n\n
When a Sub-Agent \u2014 and when not<\/h2>\n\n\n\n
Not every task needs a Sub-Agent. Too many often lead to worse results. A simple question helps.<\/p>\n\n\n\n
Will this 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\n\n
Use Sub-Agents when many files are read, when jobs run in parallel, or when you want an unbiased review.<\/p>\n\n\n\n
Skip them for small changes, for steps that depend on each other, or when the agent would have to ask a follow-up question.<\/p>\n\n\n\n
Dynamic workflows and \u201eultra code\u201c<\/h2>\n\n\n\n
Since Opus 4.8 there are dynamic workflows. The main session then automatically starts many Sub-Agents in parallel. That is powerful, but it burns through your session limit fast.<\/p>\n\n\n\n
That is why the trigger word was changed from \u201eworkflow\u201c to \u201eultra code\u201c. So no large workflow starts by accident. Use the tool deliberately.<\/p>\n\n\n\n
Take permissions seriously<\/h2>\n\n\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 really needs.<\/p>\n\n\n\n
For research and review agents that usually means: read only. With third-party agent files, check for possible prompt injections beforehand.<\/p>\n\n\n\n
My promise to you<\/h2>\n\n\n\n
Sub-Agents are not an end in themselves. They are a tool for division of labour. The gain is less noise in the chat, lower costs and an unbiased look at your work.<\/p>\n\n\n\n
My promise to you: I recommend Sub-Agents only where they measurably help. Automation is more than AI hype.<\/p>\n\n\n\n
- Parallel work.<\/strong> Many independent tasks run at the same time instead of one after another.<\/li>