What are Claude Code subagents?
A Claude Code subagent is a specialized assistant that handles one kind of task in its own context window. It has its own system prompt, its own set of tools and its own permissions. When Claude hits a task that matches a subagent's description, it hands the task over. The subagent does the work and returns only a summary.
The main reason to use one is context. Searching a codebase, reading logs or running a test suite produces a lot of output you will never look at again. A subagent keeps that out of your main conversation, so your session stays focused and lasts longer. Subagents also let you limit tools (a reviewer that cannot edit files) and route cheap tasks to a faster model.
Built-in subagents
Claude Code ships with subagents it uses on its own:
| Subagent | Tools | Used for |
|---|---|---|
| Explore | Read-only, no Write or Edit | Fast file discovery and code search |
| Plan | Read-only, no Write or Edit | Research during plan mode before presenting a plan |
| General-purpose | All tools available to subagents | Multi-step tasks that mix exploring and changing code |
There are also small helpers for specific jobs, such as one that configures your status line. You do not need to call any of these yourself. If you define your own subagent named Explore at user or project level, it replaces the built-in one, which is a common way to run exploration on a cheaper model.
How to create a subagent
A subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt.
- Pick a scope. Use
.claude/agents/for a subagent tied to one project, or~/.claude/agents/for one you want everywhere. - Write the file. Save it as something like
.claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews code for quality and best practices. Use after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
- Check it loads. Claude Code watches both folders and picks up new or edited files within a few seconds. The one exception: if the
agentsfolder did not exist when the session started, restart Claude Code. - Try it. Ask:
Use the code-reviewer agent to look at my last commit.
You can also ask Claude to write the file for you by describing the subagent and where to save it. On recent versions, /agents just prints a reminder to do this or to edit the folders directly; older versions opened an interactive editor.
Where do subagents live?
Subagents live in .claude/agents/ for one project or ~/.claude/agents/ for all your projects, and can also come from managed settings, the --agents CLI flag or a plugin. When two subagents share a name, the higher-priority location wins:
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Whole organization | 1 (highest) |
--agents CLI flag (JSON) |
Current session only | 2 |
.claude/agents/ |
Current project | 3 |
~/.claude/agents/ |
All your projects | 4 |
A plugin's agents/ folder |
Where the plugin is enabled | 5 (lowest) |
Both agent folders are scanned recursively, so you can group files into subfolders like agents/review/. The subagent's identity comes from its name field, not the file path.
Frontmatter fields
Only name and description are required. Field names are camelCase and must be spelled exactly; Claude Code silently ignores fields it does not recognize.
| Field | What it does |
|---|---|
name |
Unique ID, such as code-reviewer. Cannot contain : |
description |
When Claude should delegate to this subagent |
tools |
Allowlist, like Read, Grep, Bash. Omit to inherit all tools available to subagents |
disallowedTools |
Denylist removed from the inherited or listed tools |
model |
sonnet, opus, haiku, fable, a full model ID, or inherit |
permissionMode |
default, acceptEdits, auto, dontAsk, bypassPermissions or plan |
maxTurns |
Cap on agentic turns before the subagent stops |
skills |
Skills whose full content is preloaded at startup |
mcpServers |
MCP servers this subagent can use, by name or inline config |
hooks |
Hooks that run only while this subagent is active |
memory |
Persistent memory scope: user, project or local |
effort |
Effort level while this subagent runs |
isolation |
worktree runs it in a temporary git worktree |
background |
true keeps it in the background even when Claude asks to wait |
color |
Display color in the task list |
Subagents installed from a plugin ignore hooks, mcpServers and permissionMode for security reasons. Copy the file into your own agents folder if you need them.
Choosing tools
Use tools as an allowlist or disallowedTools as a denylist. If both are set, the denylist applies first.
---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---
You can also target whole MCP servers: mcp__github__* in tools gives every tool from the github server, and mcp__* in disallowedTools removes every MCP tool. A denylist entry like Bash(git push *) removes Bash entirely, not just that command. To keep Bash but block specific commands, add a deny rule to permissions.deny in your settings instead.
When does Claude use a subagent?
Claude delegates to a subagent based on your request, each subagent's description, and the current context. Three ways to steer it, from lightest to strongest:
- Name it in your prompt:
Have the debugger subagent look at this stack trace.Claude usually delegates. - @-mention it: type
@and pick the agent from the list. This guarantees that subagent runs for the task. - Run the whole session as it:
claude --agent code-reviewer, or set"agent": "code-reviewer"in.claude/settings.json. The main thread takes on that agent's prompt, tools and model.
To encourage automatic delegation, write descriptions that say exactly when to use the agent, and add phrases like "use proactively". Keep them short: all your subagent descriptions load into context, and Claude Code warns at startup when they pass 15,000 tokens combined.
Subagents can spawn their own subagents up to three layers deep by default. A subagent Claude spawns from the main conversation starts in the background by default, and permission prompts it needs still surface in your main session.
Four example subagents
Read-only code reviewer
---
name: code-reviewer
description: Expert code reviewer. Use proactively right after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer.
When invoked:
1. Run git diff to see recent changes.
2. Focus on the modified files.
3. Report issues grouped as Critical, Warnings and Suggestions.
For each issue give the file, the line, why it matters and the smallest fix.
Skip style nits a formatter would catch.
Test runner on a cheaper model
---
name: test-runner
description: Runs the test suite and reports failures. Use after code changes or when asked to run tests.
tools: Bash, Read, Grep
model: haiku
---
Run the project's test command. If everything passes, reply with one line.
If tests fail, list each failing test with the assertion message and the
most likely file to look at. Do not try to fix anything.
Test output is long and repetitive, which is exactly what you want out of your main context.
Debugger that can edit
---
name: debugger
description: Debugging specialist for errors, test failures and unexpected behavior. Use when something breaks.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert at root cause analysis.
1. Capture the error message and stack trace.
2. Find the steps to reproduce it.
3. Isolate where it fails.
4. Make the smallest fix that addresses the cause, not the symptom.
5. Run the failing test again to confirm.
Report the root cause, the evidence, and the fix.
Read-only database analyst with a guard hook
---
name: db-reader
description: Runs read-only database queries. Use when analyzing data or building reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Run SELECT queries to
answer questions. If asked to change data or schema, explain that you
only have read access.
The hook script reads the command from stdin and exits with code 2 if it contains INSERT, UPDATE, DELETE, DROP or similar. See the hooks guide for how exit codes work.
Subagents vs skills
Subagents and skills are both Markdown files with frontmatter, and they solve different problems.
| Subagent | Skill | |
|---|---|---|
| Runs in | Its own context window | Your main conversation |
| Returns | A summary | Its work happens inline |
| Tools | Can be restricted per agent | Uses the session's tools (with optional pre-approvals) |
| Best for | Noisy research, isolated reviews, tasks with tight tool limits | Repeatable procedures, checklists, house style, reference material |
| File | .claude/agents/<name>.md |
.claude/skills/<name>/SKILL.md |
They combine well. A subagent can preload skills with the skills field, and a skill can run inside a forked subagent with context: fork. A good rule: if you keep pasting the same instructions, make a skill. If a task floods your context or needs tight tool limits, make a subagent. Stay in the main conversation for quick edits and work that needs a lot of back and forth.
Your subagent prompts are worth keeping. Kipt stores prompts and skills in a private GitHub repo you own, so the system prompt you wrote for a reviewer agent is one ⌘K search away, and the free SKILL.md generator can turn the same text into a skill when you want it to run inline instead.
Source: Create custom subagents in the Claude Code docs.