Picture Claude Code as a consultant with a small team. You only talk to the consultant. He hands subtasks to specialists and reports the result back to you at the end.
That is exactly what Sub-Agents are. Not hype, but a practical tool for division of labour. This post shows when they are worth it — and when not.
What a Sub-Agent is
The main session is the orchestrator. That is the instance you talk to. It starts independent Sub-Agents and assigns tasks to them.
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.
Why they are worth it
Four reasons make Sub-Agents useful.
- Clean context. Research, long logs and large reports stay out of the main chat.
- Parallel work. Many independent tasks run at the same time instead of one after another.
- Cheaper models. A small model does the legwork, a strong one stays in charge.
- Honest reviews. A fresh agent is not conditioned to agree with you.
Built in or self-built
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.
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.
A common mistake in practice is a forgotten quotation mark. Then the structure breaks, and the agent never starts.
Project or global
Project-scoped agents live in the repo and travel with it. Global agents live in your user folder and belong only to you.
Rule of thumb: if the team should use it, it belongs in the project. Moving it is trivial, because it is just one file.
When a Sub-Agent — and when not
Not every task needs a Sub-Agent. Too many often lead to worse results. A simple question helps.
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.
Use Sub-Agents when many files are read, when jobs run in parallel, or when you want an unbiased review.
Skip them for small changes, for steps that depend on each other, or when the agent would have to ask a follow-up question.
Dynamic workflows and „ultra code“
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.
That is why the trigger word was changed from „workflow“ to „ultra code“. So no large workflow starts by accident. Use the tool deliberately.
Take permissions seriously
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.
For research and review agents that usually means: read only. With third-party agent files, check for possible prompt injections beforehand.
My promise to you
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.
My promise to you: I recommend Sub-Agents only where they measurably help. Automation is more than AI hype.
Note: This post summarises the core ideas of an English-language YouTube video on Claude Code Sub-Agents and places them in a consulting context. Source: youtube.com/watch?v=e18sdZLwP7o.