Claude Code Subagents: A Practical Guide

August 10, 2026 claude-codesubagents

Subagents are how Claude Code does more than one thing at a time without making a mess. Each one runs in its own context window with its own system prompt, its own tool permissions, and its own model choice, then reports back a result instead of dumping its working notes into your conversation. This guide covers where the files live, the frontmatter fields worth knowing, how delegation actually triggers, and a complete example you can copy. Verified against the Claude Code docs as of August 2026.

Why subagents exist

Two problems, one mechanism.

Context pollution. A big research task (find every place we handle currency, read all of them, summarize the patterns) can burn most of a context window on file dumps you never need to see again. Run it in a subagent and your main session receives only the conclusion.

Scoped behavior. Sometimes you want a worker with different rules: a reviewer that can read but never edit, a migration writer pinned to a stronger model, a cleanup task that should run on a cheaper one. A subagent carries its own system prompt, tool list, and permission mode, so the constraints are structural rather than hopeful.

The core fact to internalize: a subagent gets a separate context window. It does not see your conversation history, and your conversation does not see its intermediate work. You are passing a task description across a wall and getting a report back. Write the delegated task the way you would brief a contractor, because that is mechanically what is happening.

Where agent files live

A subagent is a markdown file with YAML frontmatter. Claude Code looks for them in several places, highest precedence first:

Discovery walks up from your working directory scanning .claude/agents/ in each parent, and when nested directories define the same agent name, the one closest to where you are working wins. Project agents belong in version control for the same reason project skills do: the whole team inherits them.

In recent versions the /agents command no longer opens an interactive creation wizard; it points you at the simpler truth, which is that you can just ask Claude to write the agent file, or create it yourself in .claude/agents/.

A complete working example

Here is a read-only agent we keep in repos with a real test suite. File: .claude/agents/test-auditor.md.

---
name: test-auditor
description: Audits test coverage for a feature or module. Use
  proactively after implementing a feature, or when the user asks
  what is untested, where coverage gaps are, or whether tests are
  meaningful.
tools: Read, Grep, Glob
model: inherit
---

You are a test quality auditor. Given a feature area or module:

1. Find the implementation files and their corresponding tests.
2. Report which public behaviors have no test at all.
3. Flag tests that assert nothing meaningful (no assertions,
   snapshot-only, or asserting mocks rather than behavior).
4. Rank the gaps by risk: data loss and money paths first.

Report format: a short table of gaps (behavior, file, risk),
then at most five recommended test cases with one-line
descriptions. Do not write the tests. Do not modify any file.

The pieces doing the work:

• description is the routing rule. Claude reads it to decide when to delegate. The phrase "use proactively" is a documented nudge that makes automatic delegation more likely, and listing literal user phrasings ("what is untested") gives the matcher something to match.
• tools: Read, Grep, Glob makes the agent structurally read-only. It is not being asked nicely to avoid edits; it does not have the tools.
• The body is the agent's entire system prompt. Unlike a skill, which injects instructions into the current conversation, this text replaces the default behavior for the subagent. Write it as a role definition with a fixed output format, so results come back in a shape you can act on.

Ask "run the test-auditor on the billing module" and Claude delegates; or finish a feature and a well-written description means it often delegates on its own.

The frontmatter fields that matter

name and description are required (name: lowercase letters and hyphens). The rest are optional. The ones we actually reach for:

• tools / disallowedTools: allow or deny lists for the agent's tools. If tools is omitted the agent inherits everything available to subagents. MCP servers can be granted with patterns like mcp__github__*.
• model: an alias like sonnet, opus, or haiku, a full model ID, or inherit (the default) to use the main conversation's model. Cheap model for mechanical work, strong model for judgment work.
• permissionMode: the agent's own permission stance, such as default, acceptEdits, or plan. A research agent in plan mode cannot surprise you.
• maxTurns: hard cap on agentic turns. Cheap insurance on agents that might loop.
• skills: a list of skill names preloaded into the agent's context at startup, full content included. This is the composition story: procedures live in skills, and an agent declares which procedures it starts with.
• memory: give the agent persistent cross-session memory scoped to user, project, or local. An auditor that remembers last week's findings is noticeably more useful than one with amnesia.
• background: run the agent as a background task while you keep working.
• isolation: worktree: run the agent in a temporary git worktree, so its file changes happen on an isolated copy rather than your checkout.
• color: cosmetic, but with four agents running, transcript color-coding stops being cosmetic.

How delegation triggers

Three escalating levels of control:

1. Automatic. Claude matches your request against agent descriptions and delegates when one fits. Quality of the description field is nearly the whole game here.
2. Explicit, one task. Mention the agent by name in your prompt, or @-mention it as @agent-test-auditor to guarantee that agent handles the task.
3. Session-wide. Launch with --agent <name> (or set it in settings) and the entire session runs as that agent: its system prompt, tools, and model.

There is also an escape hatch worth knowing for one-off setups: the --agents CLI flag accepts JSON agent definitions for just that session, no files involved.

The built-in agents

Claude Code ships with a few subagent types, and two of them explain a lot of behavior you may have noticed:

• Explore: read-only file discovery and code search. It deliberately skips loading CLAUDE.md files and git status to stay fast and cheap.
• Plan: read-only research used during plan mode, same trimmings.
• general-purpose: the kitchen-sink agent with full subagent tool access, for multi-step tasks that need both exploration and modification.

The design lesson from Anthropic's own defaults: most delegated work is research, research agents should be read-only, and they should carry the minimum context that lets them answer.

Patterns that hold up

• Brief like a contractor. The agent cannot see your conversation. Name the files, the goal, and the output format in the delegation, or you will get back a well-executed answer to the wrong question.
• Read-only by default. Grant Edit and Write only to agents whose job is producing changes. Every other agent gets Read, Grep, Glob and becomes impossible to blame for a broken build.
• Fixed report formats. Agents that return "a table of gaps plus five recommendations" compose into workflows. Agents that return essays do not.
• Don't parallelize edits to the same files. Parallel research is free; parallel writers clobber each other. Fan out reads, serialize writes.

FAQ

What is the difference between a subagent and a skill?

A skill is instructions loaded into the current conversation: same context, same permissions. A subagent is a separate worker: own context window, own system prompt, own tool limits. Procedures belong in skills; roles with different rules or big context appetites belong in subagents. The skills frontmatter field lets an agent preload the procedures it needs, so the two compose cleanly.

Do subagents see my CLAUDE.md?

Custom subagents run with their body as the system prompt and their own context. The built-in Explore and Plan agents explicitly skip CLAUDE.md and git status. Either way, do not assume project instructions made it across the wall: put anything critical in the agent file itself or in a preloaded skill.

Do subagents cost more?

Each runs in its own context window, so a delegation spends tokens on its own system prompt and exploration. You come out ahead when the task would have flooded your main context (big research) or when you pin mechanical work to a cheaper model. For a one-file question, just asking in the main session is cheaper.

Can subagents run in parallel?

Yes, and parallel research is one of the main reasons to use them. Keep parallel agents off the same files unless they are read-only.