Claude Code Subagents: How to Create and Use Them

Context is the scarcest resource in a Claude Code session (our context management guide covers the other levers). Every file Claude reads and every test log it sees fills the same window, and quality drops as it fills. Subagents solve this by running work in a separate context window and handing back only a summary.

This guide explains how subagents work, how to write your own, and the patterns that make them worth the overhead. Details are checked against the official Claude Code documentation as of October 2026.

What a subagent is

A subagent is a specialised assistant defined in a Markdown file with YAML frontmatter. The frontmatter configures it (name, description, tools, model); the body becomes its system prompt. When Claude delegates to it, the subagent:

• starts with its own context window, not your conversation history;
• receives its system prompt plus basic environment details, and by default your CLAUDE.md files;
• uses only the tools you allow;
• returns a summary to the main conversation when it finishes.

That isolation is the point. A subagent can read 200 files or a 10,000-line test log, and your main session only receives the conclusion. Building agents outside Claude Code? See Claude agents explained.

Built-in subagents

Claude Code already includes several subagents and uses them automatically:

Agent	Tools	Used for
Explore	Read-only (Write and Edit denied)	Fast file discovery and codebase search. Claude picks a thoroughness level: quick, medium or very thorough.
Plan	Read-only	Gathering context during plan mode before presenting a plan
General-purpose	All tools available to subagents	Multi-step tasks that need both exploration and changes
claude-code-guide	—	Answering questions about Claude Code itself
statusline-setup	—	Configuring the status line via /statusline

Explore and Plan start without your CLAUDE.md files and git status snapshot to keep research fast and cheap. A custom subagent named Explore overrides the built-in one, which is a simple way to run exploration on a smaller model.

Creating your first subagent

The quickest route is to ask Claude to write it:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. Make it read-only and have it use Sonnet.

Or write the file yourself. Save this as .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Claude Code watches the agents directories and picks up new or edited files within seconds. One exception: if the agents directory didn’t exist when the session started, restart Claude Code.

Where subagent files live

Location	Scope	Priority
Managed settings	Organisation-wide	1 (highest)
--agents CLI flag (JSON)	Current session only	2
.claude/agents/	Current project (commit it)	3
~/.claude/agents/	All your projects	4
Plugin agents/ directory	Where the plugin is enabled	5 (lowest)

When two subagents share a name, the higher-priority location wins. Directories are scanned recursively, so you can organise files into agents/review/ or agents/research/. Identity comes only from the name field, so keep names unique.

For quick experiments or CI scripts, define subagents inline:

claude --agents '{
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Frontmatter fields

Only name and description are required. Multi-word fields use camelCase.

Field	Purpose
name	Unique identifier (no :, which is reserved for plugin-scoped names)
description	When Claude should delegate to this subagent. Add “use proactively” to encourage automatic delegation.
tools	Allowed tools, e.g. Read, Grep, Glob. Omit to inherit every tool available to subagents.
disallowedTools	Tools to remove from the inherited or listed set
model	sonnet, opus, haiku, fable, a full model ID, or inherit
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions or plan
maxTurns	Stop after N agentic turns
skills	Skills to preload in full at startup
mcpServers	MCP servers available only to this subagent
hooks	Hooks scoped to this subagent’s lifetime
memory	Persistent memory scope: user, project or local
isolation	worktree runs it in a temporary git worktree
effort	Effort level while active
omitClaudeMd	Start without your CLAUDE.md files
color	Display colour in the task list

Plugin subagents ignore hooks, mcpServers and permissionMode for security reasons. Copy the file into .claude/agents/ if you need them.

Choosing tools and models

Restrict tools to the job. A reviewer doesn’t need Edit or Write. A researcher doesn’t need Bash. Fewer tools means fewer ways to go wrong and fewer permission prompts.

Match the model to the task. The model is resolved in this order: a per-invocation model Claude passes, then the subagent’s model field, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation’s model. Search and summarisation often run fine on haiku; tricky debugging may deserve inherit or a larger model.

Scope MCP servers. Put a heavy MCP server (say, a browser) in one subagent’s mcpServers rather than in every session.

Invoking subagents

Three levels of control:

1. Automatic delegation. Claude matches your request against each subagent’s description.
2. Natural language. “Use the code-reviewer subagent to look at my recent changes.” Claude usually delegates.
3. @-mention. Type @ and pick the agent from the typeahead, or write @agent-code-reviewer. This guarantees that subagent runs for the task.

For a whole session, start Claude Code with --agent <name> so the main conversation itself runs as that agent.

Note that /agents in current versions prints a reminder to ask Claude or edit the agents folders directly; older versions (v2.1.197 and earlier) opened an interactive manager.

Background, nesting and limits

• Background by default. Subagents Claude spawns from the main conversation start in the background, so you can keep working. Permission prompts surface in your main session, labelled with the subagent’s name.
• Nesting. A subagent can spawn its own subagents, up to three layers below the main conversation by default (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes it; 1 disables nesting).
• Concurrency. With 20 subagents running, new spawns fail until one finishes (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes it).
• Forks. /subtask <task> starts a fork, a subagent that inherits the entire conversation. Use it when the side task depends on what you’ve already discussed.

When workers need to message each other, or a job needs dozens of them, compare agent teams and dynamic workflows in our guide to multi-agent Claude Code.

Persistent memory

Add memory: project (or user, local) and the subagent gets a directory that survives across sessions, such as .claude/agent-memory/<agent-name>/. Its system prompt includes the first 200 lines or 25KB of that directory’s MEMORY.md. A reviewer with memory gradually learns your codebase’s recurring issues.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Patterns that work

Isolate high-volume operations

Use a subagent to run the test suite and report only the failing tests with their error messages

Parallel research

Research the authentication, database, and API modules in parallel using separate subagents

Each explores independently; Claude synthesises. Remember that every result returns to your context, and each subagent spends its own tokens.

Chain specialists

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Adversarial verification

After Claude implements a change, ask a read-only reviewer to try to break it. The agent doing the work shouldn’t be the only one grading it. Pair this with our code review prompt as the reviewer’s system prompt.

Preload conventions

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

The listed skills are injected in full at startup.

When not to use a subagent

Stay in the main conversation when:

• the task needs frequent back-and-forth;
• planning, implementation and testing share a lot of context;
• it’s a quick, targeted change;
• latency matters (a fresh subagent has to gather context first).

For a quick question about something already in context, /btw is lighter: it sees your conversation but adds nothing to history.

Guardrails with hooks

Subagents support hooks in their frontmatter, and project-level hooks can react to SubagentStart and SubagentStop events. A common pattern is a PreToolUse hook on a database subagent that blocks SQL write statements, so a “read-only analyst” really is read-only. See the hooks guide.

Putting subagents in your kit

A typical team kit commits three or four subagents to .claude/agents/: a code reviewer, a test runner, a security reviewer and maybe a docs writer. Package them with your skills and hooks in a plugin once they stabilise. For the bigger picture, see What is a Claude kit?, and for ready-made agent collections, browse the tools directory.