Claude Code Subagents Explained: What They Are and When to Use Them

Agents are not just skills in disguise

A common first reaction to Claude Code agents is that they're a skill with extra steps, a "smarter skill" that behaves more autonomously because its instructions happen to be phrased differently. That picture is mistaken. An agent is indeed a prompt, much as a skill is. The difference that matters is where it runs. An agent doesn't execute inside the main conversation. It gets its own context window, its own system prompt, its own tool access and its own permissions, works on the side, and hands back a result.

What follows starts from the basics: what these agents are, how to build one, and when the effort pays off. It assumes you already use Claude Code and want to understand the feature properly before changing any configuration. The order is the vocabulary problem first, then the reasons subagents exist, then a first custom subagent, then how they differ from skills, then working practices, a glance at agent teams, and finally the cases where an agent is the wrong choice.

Four things people mean by "agent"

In Claude Code the word "agent" covers at least four separate things, and mixing them up makes the whole feature harder to think about. A little pedantry here pays off, because it maps vocabulary onto assets you can actually use.

1. Claude Code is itself an agentic environment. Anthropic presents it as an agentic coding assistant: it has tools and an execution loop, and it can plan and act over many steps without being prompted at each one. It is agentic before you configure anything.
2. Subagents are the custom, in-product agent primitive. When a practitioner says they're building an agent in Claude Code, they nearly always have a subagent in mind. Per the official docs, these are subagents as specialised assistants for particular kinds of task, each with a separate context window, a custom system prompt, defined tool access and independent permissions.
3. Agent teams belong to a different, multi-session feature. According to the teams documentation puts the boundary plainly: subagents live inside one session, whereas teams coordinate across several. A team is a set of independent Claude Code instances that talk through a shared task list and direct messages between peers. The feature is experimental, off by default and switched on with an environment flag. It isn't "more subagents". It sits on a different layer of the architecture.
4. The Claude Agent SDK is a fourth layer. It exposes the same tools and agent loop that power Claude Code as a Python and TypeScript library, for teams that build their own agent applications outside the CLI.

The rest concentrates on the second item, subagents. Teams deserve their own treatment later; one subagent explained thoroughly is the right place to begin.

Why subagents exist

The root cause is that language models have finite context, and sooner or later a long session hits the limit. Without some countermeasure, it happens again and again.

Anthropic's essay about curating context describes the discipline as curating what goes into a limited window. Each tool call, file read and half-finished analysis is appended to context and remains. The longer a session runs, the more of the window is taken by scaffolding that helped reach an answer yet is useless afterwards. That clutter hurts quality, a decay often labelled rot in the window. The model has less space to work in, and more irrelevant material competes for its attention.

Subagents are one remedy. The Claude Code features overview says it directly: a subagent may read dozens of files or run extensive searches, yet the main conversation receives only a summary, so the intermediate work never uses up the main context. That's handy whenever the intermediate steps don't need to stay visible.

A concrete case: you ask Claude to find out why a test suite is failing. Done in the main session, the investigation means reading twenty files, grepping for error patterns, checking test configuration and scanning recent commits. All of it ends up in your context. By the finish you've spent several thousand tokens on intermediate work, and nearly none of it affects what you do next.

A subagent reshapes the problem. The investigation happens in its own context window and its own token budget, and what comes back is a short verdict, along the lines of "the breakage traces to an environment variable absent from the CI setup; three tests are hit, and here is the repair". The main thread never absorbs the search noise.

Context isolation is the headline reason, and three smaller ones go along with it:

1. Specialisation. A subagent carries its own system prompt. A focused reviewer with instructions about your team's standards will be steadier than a general assistant trying to hold those standards next to everything else it knows.
2. Constraint enforcement. You decide exactly which tools a subagent may use. A read-only research agent that can't write files or run shell commands has a very different risk profile from the main assistant, and those limits are declared and enforced rather than hoped for.
3. Cost control. A subagent can run on a different model. Sending light tasks to Haiku while the main session uses Sonnet is a practical way to manage spend, one many people only discover after an unpleasant bill.

Building a first custom subagent

Technically a subagent is nothing more than a Markdown document with a YAML header. Two locations are valid:

• .claude/agents/ inside a project, for agents tied to that codebase. Commit these so the team can share and improve them.
• ~/.claude/agents/ in the home directory, for personal agents available in every project.

The frontmatter deserves attention

People tend to skim the YAML frontmatter, but Claude Code keeps it in the main session's memory to learn what each agent is for. In effect it is the agent's summary. Two fields are required and several more are optional. A simple example shows how they fit together:

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
             Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback on code quality, security, and best practices.
Focus on what matters. Don't restate what the code does — say what's wrong
or good about it. Flag security issues first, then logic problems, then style.

Going field by field:

• name is the unique identifier, lowercase with hyphens only. Logs display it, and Claude uses it to name the agent internally.
• description matters most. Claude consults it to decide whether a task belongs with this agent, so it should describe behaviour: the job the agent does and the moments to call on it. Including "use proactively" is a documented cue telling Claude to activate the agent without waiting for an explicit request. Drop the phrase if the agent should respond only when asked directly.
• tools limits what the agent can reach. The reviewer above can read files and search but can't edit, run shell commands or make network calls. That's deliberate: a read-only reviewer can't accidentally change what it's reviewing. The documentation itself advises granting just the tools an agent needs, for security and to keep its behaviour predictable.
• model routes the agent to a particular model: sonnet, opus, haiku, or a full ID such as claude-opus-4-6. Without it the agent uses inherit, meaning the same model as the main session.
• Everything under the frontmatter becomes the agent's system prompt. That prompt, plus the working directory, is all the agent receives from the main session.

The full reference of optional fields shows how much more can be tuned: permissionMode, maxTurns, skills, mcpServers, effort, memory, hooks, disallowedTools, color and others.

Having seen one agent, you may think it's close to a skill. You'd be partly right and partly missing the point, which the next sections unpack.

Where the file goes

Save the example as .claude/agents/code-reviewer.md in the project. The resulting layout looks like this:

your-project/
├── .claude/
│   ├── agents/
│   │   └── code-reviewer.md          ← your new agent file
│   ├── skills/
│   └── rules/
├── src/
├── tests/
├── README.md
└── package.json

After saving, Claude detects the agent. Ask it to review code changes and it delegates to code-reviewer on its own, based on how well the request matches the description. For a personal agent that works across all projects, move the file to ~/.claude/agents/code-reviewer.md. Format and contents stay identical; only the location changes.

Agents versus skills

Why the two get confused

Three similarities explain most of the mix-up:

1. Both are set up through a plain folder structure, inside .claude/skills or .claude/agents.
2. Both use frontmatter, and in both the description is the single most important setting.
3. Both are bundles of instructions, in other words prompts. A skill and an agent could contain exactly the same words.

Seen that way, they look structurally alike.

Where the work happens

Yet one visible, practical difference separates them: where the work is done, which is to say where the tokens are spent. It's the simplest distinction to grasp.

• A skill is pulled into the running conversation. Its instructions, templates and supporting files join the active context, Claude works through them in the same thread, and each step adds to the main window.
• A subagent runs separately in its own context window. It does the work, and the main conversation gets back a result.

Tuning surface

Earlier came a long list of fields an agent can set in its frontmatter. By contrast, skills accept a much shorter list, partly different too. That hints at how much more control agents give. It isn't a case for turning everything into an agent. The point is that the mental model used to design a dependable setup may need rethinking.

One task, two answers

Take the example of wanting your team's code review standards applied consistently.

Should Claude be aware of those standards for a whole session, using them while it writes code, quoting them in advice and pointing out violations as they appear, a skill fits. Write the standards one time and Claude pulls them into context when they become relevant, so everything done in the session can rely on them.

If instead you want forty files reviewed in one pass without the main context filling with file reads, interim comments and search results, that's a subagent. Configure a code-reviewer agent, let it work in its own window, and take back a structured summary. You could even launch forty subagents in parallel, one per file. The main conversation receives the outcome without the work that produced it.

One sentence captures the split: a skill changes what Claude knows or how it approaches a workflow, while a subagent changes who does the work, in which context and with which tools.

Working practices that hold up

Treat the description as a routing interface

This gets less emphasis than it should. Claude reads subagent descriptions to decide when to delegate, and it does not read the body before deciding. Anything specific you put in the prompt body stays invisible until the subagent has already been spawned. The description therefore has to carry enough information for Claude to know when the agent is needed.

• Use specific, behavioural wording.
• Say what the agent does, and in which situations it should be chosen.
• Mention the kinds of task it handles well and, where useful, the ones it shouldn't touch.
• "Use proactively after code changes" is a tested pattern, mentioned in the documentation as a way to encourage delegation without an explicit request. Omit it for agents that should only run when invoked directly.
• Avoid descriptions that state the agent's identity, like "an expert reviewer with twenty years of experience". That belongs in the system prompt. The description serves the routing model, not the agent.

To see the gap, put a vague description ("Helps with code quality and review tasks") next to one written for routing: "Looks at staged changes for security flaws, logic bugs and style problems. Run it proactively after every sizeable edit. It never writes code or edits files."

Restrict tools on purpose

An agent that inherits every tool from the main session is hard to reason about when something goes wrong. Grant only what the job needs.

• A reviewer should be able to read, and nothing beyond that: no writing, no shell, no network.
• Research work calls for search and fetch, with no ability to edit files.
• Running tests means Bash access but no reason to touch the web.

Restricting tools helps with security and with clarity. A narrow tool set makes behaviour predictable, and when the agent fails or returns something odd, a short list of possible tools speeds up diagnosis. It also makes failure modes finite and knowable. The disallowedTools field lets an agent inherit the main session's tools and then drop specific ones, which suits cases like "everything except Bash" or "everything except Write".

Give each agent one job

The subagent documentation is blunt that each subagent should excel at a single task. A description such as "reviews code, writes tests, updates documentation and handles deployment checks" puts four descriptions into one field. Claude may route to it unevenly, and the system prompt has to cope with four operating modes at once.

Narrow the scope and make three separate files, each with one clear description. In data science that might be a model validation agent, a data quality checker and a notebook reviewer. In software it might be a code reviewer, a test generator and a documentation updater. The principle holds in any field. Each agent gets a single job, its own file, and a description that routes without ambiguity.

Use the model field to manage cost

People who haven't yet been surprised by their usage bill tend to ignore this field most. Setting model: haiku on lightweight agents cuts cost noticeably when several agents run in a session. Setting model: opus on an agent that must reason at length over a large context justifies its price. Leaving the default, inherit, means every agent runs on whatever the main session uses, often the most capable model, applied equally to tasks that don't need it.

What the community has settled on

The VoltAgent subagent collection catalogues more than a hundred specialist subagents, spanning language experts, security reviewers, debuggers, infrastructure helpers and orchestrators. A second good set sits in the Everything Claude Code repository Few people would need even a fifth of them, so the count isn't the interesting part. The structure is. Every entry in these collections is narrow in scope, whether it's a TypeScript specialist, a SQL expert, a Kubernetes operator or a security auditor. None tries to cover more than one domain. That is the consensus after more than a year of real use: many focused agents beat one general-purpose agent.

A short look at agent teams

Agent teams are worth knowing about, but they are a different feature from subagents.

Subagents stay within one session. The main Claude Code instance spawns them, they work in isolation and return results, and you stay the orchestrator.

Agent teams are independent Claude Code sessions that talk to one another through a shared task list and direct peer messaging. Every teammate has its own context window and session state, and can assign tasks to others as well as receive them.

The teams documentation lists where the extra machinery helps: research or review with several teammates probing different angles together; debugging by competing hypotheses, with teammates picking at each other's theories; and building new modules where each teammate owns its own component and avoids colliding with the others.

Setting them up isn't straightforward, so they are outside the scope here, and there's no reason to jump on the bandwagon out of fear of missing out. Teams add coordination overhead and burn considerably more tokens, since each teammate has its own context window billed independently. They're experimental and disabled by default, enabled through an environment variable.

A practical rule: as long as your subagents report back to you and don't need to talk to each other, teams aren't needed. When one subagent has to hand findings to another, or question another's conclusions, the upgrade starts to earn its cost. Until then, subagents are enough.

When an agent is the wrong tool

Anthropic's own guidance on building effective agents is worth taking seriously. It recommends finding the simplest workable solution and adding complexity only when it's needed, which may mean not building agentic systems at all.

That applies directly. A few situations where a subagent adds friction and returns nothing:

• One-off tasks. A subagent carries authoring overhead: naming, writing the description, choosing tools, testing, maintenance. A job you'll do once doesn't justify that, so write a good prompt instead. The investment only returns when a workflow recurs often enough to be worth maintaining a definition.
• Cases where context isn't the problem. The main reason to use a subagent is to shield your main context from heavy work. If the task is light, the window isn't filling up and no special tool limits are needed, a subagent just adds indirection. Plain prompting in the main session wins on speed, simplicity and ease of debugging.
• The monolith trap. A single agent that tries to cover research, implementation, review and documentation isn't comprehensive. It is untestable and chosen inconsistently. A tighter, more specific description routes with far better consistency.

The general principle is to reach for the simplest tool that solves the real problem. Add agents when the issue is context isolation, specialised constraints or dedicated execution, not because agents feel more powerful.

The short version

Put simply, subagents manage context and mark an execution boundary, though most people see them as a capability boost.

One carefully configured agent is a reasonable afternoon's work. There's no need for an orchestration system to get value here: a focused description, a restricted tool set and a single clear job are enough. Complexity can grow from there, but it doesn't have to start there.

Some questions are worth asking yourself. Which task in your current workflow would you most like to hand to an isolated worker, and what is holding you back? If you already use subagents, what was the first task where isolation really mattered, where running it in the main session would have caused a genuine problem? And how do you handle tool access: restricting per agent, or inheriting from the main session and trimming?