Claude Code subagents: 5 examples and best practices
How to create Claude Code subagents: file locations, frontmatter fields, five examples, best practices, and how subagents compare with agent teams and skills.
You ask Claude Code to find every place the app reads a customer's address. It opens forty files. By the time it answers, your context window is full of code you'll never need again, and the actual task hasn't started.
Subagents fix that. A subagent is a specialist Claude delegates to. It works in its own context window and returns only the result. This guide covers how to create one, five examples, and when to use subagents instead of skills or agent teams. Facts come from Anthropic's subagents and agent teams documentation, checked on 16 November 2026.
What subagents are for
Anthropic's documentation lists five reasons to use a subagent:
- Preserve context by keeping exploration and implementation out of the main conversation.
- Enforce constraints by limiting which tools a subagent can use.
- Reuse configurations across projects with user-level subagents.
- Specialize behavior with a focused system prompt.
- Control costs by sending tasks to faster, cheaper models such as Haiku.
Claude decides when to delegate by reading each subagent's description, so the description matters more than anything else in the file.
Built-in subagents
Claude Code ships with built-in subagents it uses on its own, including Explore, a fast read-only agent for searching and analyzing codebases, Plan, and a general-purpose agent. Explore and Plan start without your CLAUDE.md files, which keeps research fast and inexpensive. Custom subagents load CLAUDE.md unless you set omitClaudeMd.
How to create one
A subagent is a markdown file with frontmatter and a system prompt:
~/.claude/agents/<name>.mdis available in every project on your machine..claude/agents/<name>.mdbelongs to one project and is shared through git.
You can also ask Claude to write it: describe the agent you want, and Claude writes the file with a name, description, tools, model, and prompt.
| Field | Required | What it does |
|---|---|---|
name | Yes | Unique identifier, such as code-reviewer |
description | Yes | When Claude should delegate to it |
tools | No | Tools it can use, such as Read, Grep, Glob. Inherits all if omitted |
disallowedTools | No | Tools to remove from the inherited set |
model | No | sonnet, opus, haiku, fable, a full model ID, or inherit |
permissionMode | No | Its permission mode |
memory | No | Persistent memory: user, project, or local scope |
skills | No | Skills to preload into its context |
omitClaudeMd | No | Start without your CLAUDE.md files |
Example 1: a read-only code reviewer
The pattern from Anthropic's own walkthrough. Read-only tools mean it can't change anything.
.claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews changed code for bugs, missing tests, and security issues. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a careful code reviewer. For each issue: give the file and line, explain
the problem, and show the fix. Check error handling, missing tests, secrets in
code, and unsafe queries. If nothing is wrong, say so in one line.
Example 2: a cheap test runner
Running tests and reading failures doesn't need the biggest model. Sending it to Haiku keeps the main conversation clear and costs less.
---
name: test-runner
description: Runs the test suite and reports failures with the likely cause. Use when tests need to run or are failing.
tools: Bash, Read, Grep
model: haiku
---
Run `pnpm test`. If everything passes, reply "All tests pass" and the count.
If tests fail, for each failure give the test name, the assertion that failed,
and the most likely cause in one sentence. Don't fix anything.
Example 3: a domain expert with shared memory
With memory: project, the subagent keeps a memory directory at .claude/agent-memory/<name>/ in the repository, so what it learns is shared with the team through git. Anthropic recommends project scope as the default.
---
name: payments-expert
description: Knows the payments service. Use for any change under services/payments/.
memory: project
---
You are the team's expert on the payments service. Before answering, read your
memory for known gotchas. When you learn something that would save the next
engineer time, such as a flaky test cause or an undocumented constraint, add it
to your memory.
Review changes to its memory files in pull requests, like any other code. More on this pattern in Claude Code team memory.
Example 4: a migration reviewer that can't edit
disallowedTools removes tools from the inherited set, so this agent can run commands and read files but not write them.
---
name: migration-reviewer
description: Reviews new database migrations for locking, data loss, and missing down migrations. Use when a migration file is added or changed.
disallowedTools: Edit, Write
---
Read every migration added on this branch. For each one, check: does it lock a
large table, can it lose data, is there a down migration, will it run safely
while the old code is still deployed? Report problems with the file and line.
Example 5: a docs researcher that skips project context
Research about external libraries doesn't need your project's instructions. omitClaudeMd starts the subagent without them.
---
name: docs-researcher
description: Looks up how a third-party library or API works. Use when the task depends on external documentation.
tools: Read, WebFetch, WebSearch
model: sonnet
omitClaudeMd: true
---
Find the answer in the library's official documentation. Quote the relevant
part, give the URL, and note the version it applies to. Say clearly if the docs
don't answer the question.
Best practices
From Anthropic's documentation:
- Keep each subagent focused on one task.
- Write descriptions that point to one subagent, so Claude routes to the right one.
- Keep descriptions short. Claude Code warns at startup when the combined descriptions of your custom subagents exceed 15,000 tokens. Put detail in the system prompt, which only loads when the subagent runs.
- Limit tools to what the task needs.
- Use cheaper models for mechanical work like running tests.
Subagents vs agent teams vs skills
| Subagent | Agent team | Skill | |
|---|---|---|---|
| What it is | A specialist in its own context window | Several Claude Code instances working together | Instructions loaded into the current conversation |
| Communication | Returns a result to the caller | Teammates message each other directly | None; it is part of the conversation |
| Coordination | The main agent manages the work | Shared task list; teammates claim work | You or Claude invoke it |
| Cost | Moderate | Significantly more tokens | Low until used |
| Status | Standard | Experimental, off by default | Standard |
| Best for | Focused tasks that would clutter context | Parallel, independent work like reviews or competing hypotheses | Repeatable procedures |
Agent teams are enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Setup and best practices are in Claude Code agent teams. The documentation is direct that for sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective. For skills, see Claude Code skills: 6 examples.
What a subagent doesn't know
A subagent starts with its own context. It sees your CLAUDE.md, unless told not to, but not your main conversation, and not your auto memory. If a decision was made earlier in the session, or in a Slack thread last week, the subagent doesn't know it unless something puts it in front of it.
Where Lockstep fits
Lockstep keeps the team's approved decisions in one record that any agent can query. Decisions are captured from PRDs, Slack, and pull requests and become binding when their owner approves them. Claude Code's main session is briefed on the ones that apply at session start. A subagent with access to Lockstep's MCP tools can look up the same decisions itself; it won't see the main session's briefing automatically.
Session briefings work with Claude Code today. See how it works.
Sources checked 16 November 2026
Related reading
For the definition, see subagents. For hooks, see Claude Code hooks: 6 examples. For sharing what agents learn, see Claude Code team memory. For giving subagents their own checkouts, see Claude Code worktrees. To compare every extension, see CLAUDE.md vs skills vs hooks vs subagents. For orchestrating dozens of subagents from a script, see Claude Code workflows. For when to use a team instead, see Claude Code subagents vs agent teams.
Frequently asked questions
- How do I create a Claude Code subagent?
- Add a markdown file to .claude/agents/ for one project or ~/.claude/agents/ for every project. Give it frontmatter with a name and a description, and optionally tools, model, and memory, then write its system prompt below. You can also ask Claude to write the file for you.
- What built-in subagents does Claude Code have?
- Explore, a fast read-only agent for searching and analyzing codebases, Plan, and a general-purpose agent, among others. Explore and Plan start without your CLAUDE.md files to keep research fast and inexpensive.
- What is the difference between subagents and agent teams?
- Subagents work inside one session and report results back to the main agent, which manages the work. In agent teams, several Claude Code instances share a task list and message each other directly. Agent teams are experimental, disabled by default, and use significantly more tokens.
- What is the difference between a subagent and a skill?
- A skill is a set of instructions loaded into the current conversation when relevant. A subagent is a separate worker with its own context window, tools, and model, which returns only its result. A skill can also run in a subagent with context: fork.
- Do subagents see my CLAUDE.md?
- Custom subagents load your CLAUDE.md files unless their definition sets omitClaudeMd. The built-in Explore and Plan subagents start without them. The main conversation's auto memory is not loaded into subagents.
Keep reading