Claude Code Agents and Subagents Explained

Claude Code agents are specialized role definitions, a system prompt, a toolset and boundaries, that turn one general AI into a named expert. Subagents are the isolated runtime workers a main session dispatches to execute those roles, each in its own clean context window, reporting back when done. Most explanations stop at the definition. This guide goes further: how the two relate, how real agents pass work to each other, and when a single agent beats a team. We can speak from production here, because we run and sell 18 specialist agents that do client work every day.

What are Claude Code agents?

An agent is a packaged identity for the AI: a markdown file that defines who the model is in this role, what it is allowed to touch, and where its job ends. A typical agent definition carries four things. A role description that narrows the model from generalist to specialist. A tool allowlist that grants only what the role needs, a content agent gets web search and file editing, not your ad account. A set of working rules, the methods, quality gates and forbidden moves of that discipline. And boundaries, an explicit list of what this agent does not do and which colleague owns that work instead.

That last part is the piece generic articles skip, and it is the part that makes agents work in practice. Browse our Claude agents, all 18 of them, and you will find the same pattern in every definition: code-architect implements and refactors but does not invent visual brand direction; seo-alchemist owns organic search analysis but hands ad-spend questions to growth-engineer; sim-matrix validates quality but writes no code at all, it only returns pass or fail. An agent without boundaries is just a renamed chatbot. An agent with boundaries is a colleague you can schedule.

The format matters less than people expect. Agent definitions are plain markdown with a small frontmatter block. They were designed for Claude Code, but because they are readable instructions rather than proprietary config, the role logic ports to any MCP-compatible AI assistant with modest adaptation.

What are subagents?

If the agent is the job description, the subagent is the worker who shows up for one shift. When a Claude Code session needs specialist work done, it dispatches a task to a subagent: a fresh instance of the model, loaded with the chosen agent definition, given a specific brief, and started with a completely clean context window.

Three properties define how subagents behave. First, isolation: the subagent does not inherit the main conversation’s history. It sees only its brief and what it discovers itself, which means no context pollution from twenty earlier topics, and no token budget wasted on irrelevant scrollback. Second, single-mission scope: a subagent runs one task to completion and returns a final report to the session that spawned it. The parent reads the report, not the subagent’s full working transcript. Third, no nesting: a subagent cannot spawn its own subagents. The hierarchy stays exactly two levels deep, one orchestrator and its workers, which keeps the system debuggable instead of fractal.

The practical payoff is parallelism. A main session can dispatch several subagents at once, one auditing analytics, one drafting content, one reviewing code, and each works in its own clean room while the orchestrator integrates the results. That is the difference between an assistant and a staffed operation.

How do agents and subagents differ?

The cleanest way to hold the distinction: an agent is a definition, a subagent is an execution. The agent is a file that exists before any work starts and persists after it ends. The subagent is a runtime event, born when a task is dispatched, gone when the report is delivered.

This is why the question “agents vs subagents, which do I need?” is slightly misframed. You do not choose between them; you need both halves. The agent file decides what kind of expert handles the work: its method, its toolset, its limits. The subagent mechanism decides how that expert runs: isolated, parallel, reporting upward. One agent definition can power hundreds of subagent runs, the same way one job description can cover years of shifts. And a single session can run subagents from many different agent definitions in the same hour, an SEO specialist in one lane and a developer in another.

There is one more asymmetry worth naming. Quality lives mostly in the agent definition; reliability lives mostly in the subagent mechanics. A vague agent file produces vague work no matter how cleanly the run is isolated. A sharp agent file still fails if every task shares one polluted context. Production setups invest in both.

How do agents hand off work to each other?

This is where most multi-agent content goes vague, so here is the dispatch model we actually run on client work, concretely.

Work enters through an orchestrator, the main Claude Code session. Before dispatching, the orchestrator writes a mission brief: the goal in one sentence, what is in scope, what is explicitly out of scope, the done criteria, and how the result will be verified. Vague dispatches produce vague work, so briefs without done criteria do not go out.

Then the chain runs. Agents do not dispatch each other directly; subagents cannot spawn subagents, so handoffs flow through the orchestrator. What each agent does instead is end its report with a handoff recommendation: who should pick the work up next and why. A web page change in our setup runs code-architect for implementation, then seo-alchemist for on-page review, then sim-matrix for quality assurance across breakpoints and accessibility. A content piece runs the writing agent, then SEO review, then publication, then a render check. The chain is a rule, not a habit: until the last link reports pass, the job does not count as finished.

Boundaries are what make these handoffs clean. Because every agent’s definition states what it does not do, there is no ambiguity about where one job ends and the next begins. The content agent writes the copy and explicitly does not run the SEO audit; the SEO agent reviews and explicitly does not rewrite voice and tone. Overlap is where multi-agent systems rot, and the cure is written ownership, agreed before any task runs.

When should you use a single agent vs a team?

The honest rule of thumb: count the domains of expertise the task touches. One domain, one agent. Two or more, a team.

A single subagent is the right call for self-contained work: a batch file rename, one focused bug fix, a research sweep, a report draft. The task starts and ends inside one specialty, so a clean dispatch with a good brief covers it, and adding more agents would only add coordination cost.

Teams earn their overhead the moment work crosses disciplines, and the failure mode of skipping the team is predictable. Send a landing page to a solo developer agent and the structure comes back right but the headings carry no search intent; the SEO reviewer flags it; the work goes back; the revision loop runs two or three times. Dispatching specialists together, with the chain enforced, catches those collisions on the first pass instead of the third. In practice almost everything client-facing, pages, campaigns, content with publication, onboarding, is multi-domain, which is why our default for real work is the chain, not the lone expert.

If you want the team without assembling it yourself, the Agency in a Box combo bundles the core agents with the skills and connectors they rely on, wired with the boundaries and handoff rules described above. To round out the concept map first, see what Claude skills are, skills give an agent its method, and what MCP is, MCP gives it access to live systems. Agents are the third layer: the roles that decide who does what, and who gets the work next.