# Claude Code subagents: how to create them, with examples and best practices

A subagent takes a side task into its own context window and hands back only the answer. How to write one, which model it runs on, and when a skill or an agent team fits better.

Published 2026-10-08 by Richard Kaminsky and Mitchell Lipyansky, the co-founders of Poly. Canonical: https://usepoly.co/claude-code-subagents
Poly is a multiplayer AI coding workspace: a shared room where your team works with one AI agent, together. Free to start: https://usepoly.co/

**A Claude Code subagent is a helper Claude starts for a side task: it "runs in its own context window with a custom system prompt, specific tool access, and independent permissions," then returns only a summary, so your main conversation stays clean. Claude Code ships three you'll see most, Explore, Plan and general-purpose, and you can write your own as a Markdown file in `.claude/agents/` with a name and a description. Since July 2026 subagents run in the background by default, up to 20 at a time, and they can start their own subagents up to three layers deep. Their requests count toward the same usage limits as your conversation.**

## Key takeaways

- **What it is:** a separate context window with its own prompt, tools and permissions, returning a summary ([Anthropic](https://code.claude.com/docs/en/sub-agents)).
- **Make one:** ask Claude to write it, or save a Markdown file with `name` and `description` in `.claude/agents/` (project) or `~/.claude/agents/` (you).
- **Model:** inherits your conversation's model unless the file or `CLAUDE_CODE_SUBAGENT_MODEL` says otherwise.
- **Runs:** in the background by default, in parallel, up to 20 at once and three layers deep.
- **Cost:** no discount; a subagent's tokens come out of your plan or API bill like any other.

*From Anthropic's subagent, features overview and agent teams docs, October 8, 2026.*

|  | Subagent | Skill | Agent team |
| --- | --- | --- | --- |
| What it is | A helper with its own context window | Instructions loaded when relevant | Several Claude Code sessions with a lead |
| Context | Separate; returns a summary | Adds to your main conversation | Each teammate has its own |
| Talks to others | Returns a result; named ones can message each other | No | Teammates message each other |
| Defined in | .claude/agents/<name>.md | .claude/skills/<name>/SKILL.md | Started by the lead in a session |
| Token cost | Lower: only the summary comes back | Whatever it adds to the conversation | About 7x in plan mode |
| Status | Stable | Stable | Experimental, off by default |

## What is a subagent in Claude Code?

Anthropic's definition: "Subagents are specialized AI assistants that handle specific types of tasks." Use one "when a side task would flood your main conversation with search results, logs, or file contents you won't reference again" ([Anthropic](https://code.claude.com/docs/en/sub-agents)). The subagent does the reading in its own context and sends back what matters.

A subagent starts with a fresh context: it doesn't see your conversation, only the task Claude writes for it. The exception is a **fork**, started with `/subtask`, which inherits the whole conversation.

## What are the built-in subagents?

- **Explore:** "A fast, read-only agent optimized for searching and analyzing codebases." It runs on your conversation's model and can't edit files. Claude asks it for a quick, medium or very thorough search.
- **Plan:** read-only research Claude uses in plan mode before presenting a plan.
- **General-purpose:** every tool, for multi-step work that both explores and changes code.
- **Helpers:** smaller agents Claude uses on its own, such as the one that sets up your [status line](/claude-code-statusline).

Explore and Plan skip your CLAUDE.md files and the git status snapshot to stay fast. Earlier versions ran Explore on Haiku; it now inherits your model, so define your own `Explore` with `model: haiku` if you want it cheaper.

## How do you create a subagent?

The quickest way is to ask: "Create a personal code-improver subagent in ~/.claude/agents/ that... make it read-only and have it use Sonnet." Claude writes the file. Or write it yourself:

```markdown
---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior reviewer. Check for bugs, security problems and
missing tests. List findings by severity with file and line.
```

Where the file lives decides who gets it. When two share a name, the higher one wins ([Anthropic](https://code.claude.com/docs/en/sub-agents)):

1. **Managed settings,** set by an organization.
2. **The `--agents` flag,** JSON for one session.
3. **`.claude/agents/`** in the project, which you commit for your team.
4. **`~/.claude/agents/`** for every project on your machine.
5. **A plugin's `agents/` folder** ([Claude Code plugins](/claude-code-plugins)).

Since v2.1.198 (July 2026), `/agents` no longer opens a wizard; it reminds you to ask Claude or edit those folders. If a new subagent doesn't show up, restart Claude Code: a running session doesn't notice a newly created `agents` folder.

## What can you put in a subagent's frontmatter?

Only `name` and `description` are required. The optional fields ([Anthropic](https://code.claude.com/docs/en/sub-agents)):

- **`tools` and `disallowedTools`:** which tools it may use, or may not.
- **`model`:** `sonnet`, `opus`, `haiku`, `fable`, a full model ID, or `inherit`.
- **`permissionMode`:** its own permission mode.
- **`maxTurns` and `effort`:** how long and how hard it works.
- **`skills` and `mcpServers`:** skills and MCP servers to load.
- **`hooks`:** hooks that run only for this subagent ([Claude Code hooks](/claude-code-hooks)).
- **`memory`:** a folder of notes it keeps between sessions.
- **`background`:** always run in the background.
- **`isolation: worktree`:** work in its own git worktree.
- **`omitClaudeMd`:** start without your CLAUDE.md files.
- **`initialPrompt`, `color` and `experimental`:** a first prompt when it runs as the main agent, a display color, and options such as a one-hour prompt cache.

Everything below the frontmatter is the subagent's system prompt.

## Which model does a subagent use?

In order: the model Claude passes when it starts the subagent, the file's `model` field, the `CLAUDE_CODE_SUBAGENT_MODEL` environment variable, then your conversation's model. `inherit` means "use the same model as the main conversation." Since v2.1.251 (August 2026) the environment variable is only a default; set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` as well to put every subagent on one model. The variable alone doesn't move Explore or Plan. Run `/tasks` to see which model each subagent is using.

A cheaper model for routine subagents is one of Anthropic's tips for [reducing token usage](/reduce-claude-code-token-usage).

## How do you use a subagent?

- **Let Claude choose:** it delegates based on the task and each subagent's description. Phrases like "use proactively" in the description encourage it.
- **Ask by name:** "Use the test-runner subagent to fix failing tests."
- **@-mention it:** `@agent-code-reviewer` "guarantees the subagent runs" for one task.
- **Make it the whole session:** `claude --agent code-reviewer` runs your main thread with that agent's prompt, tools and model.

Subagents run in the background by default in an interactive session, so you can keep working; a permission prompt from one appears in your main session with its name. Claude can start several at once for independent searches, and you can type into a running subagent's transcript to steer it.

## How many subagents can run at once, and how deep?

- **At once:** 20 by default; the 21st fails with "Concurrent subagent limit reached." `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` changes it.
- **Nesting:** a subagent can start its own, "up to three layers below the main conversation." `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1` turns nesting off.

## Subagent memory and worktrees

The `memory` field gives a subagent a notes folder that survives between sessions: `user` (yours, every project), `project` (`.claude/agent-memory/<name>/`, shareable in git) or `local` (the project, not committed). Anthropic recommends `project`. It loads the first 200 lines of the folder's MEMORY.md, as [Claude Code's memory](/claude-code-memory) does.

`isolation: worktree` runs the subagent in its own git worktree, removed afterwards if it changed nothing, so parallel subagents don't edit the same files ([Claude Code worktrees](/claude-code-worktrees)). Hooks can watch them through the `SubagentStart` and `SubagentStop` events.

## Subagent examples

Anthropic's docs include four you can copy ([Anthropic](https://code.claude.com/docs/en/sub-agents)):

- **Code reviewer:** "Expert code review specialist. Proactively reviews code for quality, security, and maintainability." Read-only tools.
- **Debugger:** "Debugging specialist for errors, test failures, and unexpected behavior."
- **Data scientist:** "Data analysis expert for SQL queries, BigQuery operations, and data insights."
- **Database query validator:** runs read-only database queries, with a hook that blocks writes.

## Subagent best practices

Anthropic's four ([Anthropic](https://code.claude.com/docs/en/sub-agents)):

1. **"Design focused subagents":** each should excel at one task.
2. **Write descriptions that single out one subagent,** because the description is how Claude picks it. All descriptions together share a 15,000-token budget.
3. **"Limit tool access":** a reviewer doesn't need Edit or Write.
4. **"Check into version control,"** so the team shares project subagents.

Its general guide adds: when Claude has to read a lot to answer a question, "use subagents to investigate" so the file contents never fill your main context ([Claude Code best practices](/claude-code-best-practices)).

## Subagents vs skills vs agent teams

- **Subagent:** a separate context that does a task and returns a summary. Use it for noisy reading, searching and checks.
- **Skill:** instructions loaded into your main conversation when relevant; it "adds to your main window" ([Claude Code skills](/claude-code-skills)).
- **Agent team:** several full Claude Code sessions with a lead, a shared task list and messages between teammates. Experimental and off by default, and Anthropic puts it at about 7x the tokens in plan mode ([agent teams](/claude-code-agent-teams)).

A skill can also run in a subagent (`context: fork`), and a subagent can preload skills (`skills`).

## Do Codex and Cursor have subagents?

Yes. Codex enables subagents by default, with built-in default, worker and explorer agents and custom ones as TOML files in `.codex/agents/` ([OpenAI](https://learn.chatgpt.com/docs/agent-configuration/subagents)). Cursor has Explore, Bash and Browser subagents, and also reads `.claude/agents/` ([Cursor](https://cursor.com/docs/subagents)).

## How have subagents changed?

- **July 24, 2025 (v1.0.60):** custom subagents and `/agents` launched.
- **October 2025:** the Explore and Plan subagents arrived.
- **December 2025:** subagents could run in the background.
- **February 2026:** agent teams (experimental), subagent memory and worktree isolation.
- **June to July 2026:** nesting, then background by default, the `/agents` wizard removed, a limit of 20 at once, and nesting three layers deep.
- **August 2026 (v2.1.251):** `CLAUDE_CODE_SUBAGENT_MODEL` became a default rather than an override.

From Anthropic's changelog ([GitHub](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)).

## Subagents for a whole team

A committed `.claude/agents/` folder gives every teammate the same reviewers and helpers, but each person still runs them in their own session. In Poly (usepoly.co), a team works with one Claude Code or Codex agent in a shared browser room, using the repository's agents and CLAUDE.md; everyone sees each step live, and any member can approve a change before it happens. Free to start. [What is Poly?](/what-is-poly)

## Common questions

**What is a subagent in Claude Code?**

A helper Claude starts for a side task. It runs in its own context window with its own system prompt, tools and permissions, and returns only a summary to your conversation. Explore, Plan and general-purpose are built in, and you can write your own.

**How do I create a Claude Code subagent?**

Ask Claude to write one, or save a Markdown file in .claude/agents/ (for the project) or ~/.claude/agents/ (for you) with name and description in the frontmatter and the system prompt below. Optional fields set tools, model, permission mode, memory and more.

**What model do Claude Code subagents use?**

Your conversation's model unless something says otherwise: the model Claude passes, the file's model field, then the CLAUDE_CODE_SUBAGENT_MODEL variable. Set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 too to run every subagent on one model.

**What is the difference between subagents and agent teams?**

A subagent works in its own context and reports back to your session. An agent team is several full Claude Code sessions with a lead, a shared task list and direct messages; it is experimental, off by default, and uses far more tokens.

**Can Claude Code subagents run in parallel?**

Yes. Claude can start several at once, and they run in the background by default, up to 20 at a time. A subagent can start its own, up to three layers deep.

More guides: https://usepoly.co/guides · Security: https://usepoly.co/security · Pricing: https://usepoly.co/pricing