A Claude Code subagent is a specialised assistant the main agent delegates a focused task to, running in its own separate context window with its own system prompt and its own scoped set of tools. Instead of the main session doing everything and filling up with noisy output, it hands a job (review this code, research this question, run these tests) to a subagent, which works in isolation and returns only a clean summary. This guide explains what subagents are, when they earn their keep, the built-in ones Claude Code ships with, and exactly how to create your own with the /agents command or a Markdown file in .claude/agents.
Part of: How to Use Claude Code: Complete Beginner Guide (2026)
What a subagent actually is
Each subagent runs in its own context window with a custom system prompt, specific tool access and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns its result. The key word is isolation: all the messy intermediate work, the dozen files it read, the failed approaches, the raw command output, stays in the subagent's window and never touches the main conversation. The main agent receives only the conclusion.
- Separate context window: the subagent does not inherit your whole main conversation.
- Custom system prompt: a short, focused brief tuned to its single job.
- Scoped tools and permissions: only what the task needs, often read-only.
- Returns a summary: the noisy work is absorbed, the main session gets the clean result.
When to use a subagent
Reach for a subagent when a side task would flood your main conversation with search results, logs or file contents you will not reference again. The subagent does that work in its own context and hands back just the answer, so your main window stays sharp and you avoid the performance cliff that hits when a context window fills with noise. Define a custom subagent when you keep spawning the same kind of worker with the same instructions: a code reviewer, a test writer, a docs generator.
- Preserve context: keep exploration and bulk reading out of your main conversation.
- Enforce constraints: limit a subagent to read-only tools so a reviewer cannot edit.
- Specialise behaviour: a focused system prompt makes it more reliable on its one job.
- Control cost: route narrow work to a faster, cheaper model like Haiku.
Built-in subagents you already have
Claude Code ships with built-in subagents it uses automatically, so you benefit from subagents before you ever create one. Explore is a fast, read-only agent for searching and understanding a codebase, often run on Haiku to keep it cheap. Plan is the research agent used in plan mode to gather context before proposing a plan. General-purpose handles complex, multi-step tasks that need both exploration and changes. You can block a built-in type via permissions if you need to, but most of the time you let them do their job.
- Explore: fast, read-only codebase search and analysis (often Haiku).
- Plan: read-only research agent that gathers context during plan mode.
- General-purpose: full-tool agent for complex, multi-step work.
Creating a custom subagent
Subagents are Markdown files with YAML frontmatter. The easiest way to create one is the /agents command, which opens a guided interface where you name the subagent, write its description, pick its tools and model, and can have Claude draft the system prompt for you. Project subagents live in .claude/agents/ (check them into version control so your team shares them); personal ones live in ~/.claude/agents/ and follow you across projects. Only name and description are required in the frontmatter; the description is what Claude reads to decide when to delegate, so write it clearly.
<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---
You are a senior code reviewer. When invoked, analyse the changed code and
return a concise, prioritised list of issues covering correctness, security
and readability. Do not edit files; only report. Cite the file and line for
each issue and suggest the smallest fix.Files added directly on disk are loaded at session start, so restart Claude Code (or create it via /agents, which takes effect immediately) to pick up a new file. The model field accepts sonnet, opus, haiku or inherit; the tools field defaults to inheriting all tools if you omit it.
Invoking and working with subagents
Most of the time you do not invoke a subagent by hand: Claude reads each subagent's description and delegates automatically when a task matches. You can also nudge it explicitly, for example "use the code-reviewer agent to review this diff". A good pattern is to write the feature with your main agent, then have it delegate the review to a read-only reviewer subagent, which inspects the diff in its own context and returns a tight issue list, after which the main agent fixes them. Because the review reasoning never loaded into your main window, the session stays clean.
Step by step
Open the subagents interface
In a Claude Code session, run /agents to open the guided interface for creating and managing subagents.
Choose a scope and create
Pick Project (.claude/agents/, shared via version control) or Personal (~/.claude/agents/, all your projects), then create a new agent. You can let Claude generate the identifier, description and system prompt.
Write a clear description
The description is what Claude uses to decide when to delegate, so state precisely when this subagent should be used. Name and description are the only required fields.
Scope tools and model
Restrict tools to what the task needs (for a reviewer, read-only) and choose a model. Route narrow work to a cheaper model like Haiku to control cost.
Save and try it
Save the subagent and test it by asking Claude to use it. If you created the file directly on disk instead, restart the session so it loads.