Claude Code Subagents Documentation and Examples

Direct answer

Claude Code subagents are specialized assistants inside Anthropic's Claude Code coding agent. Each handles a bounded side task in a separate context and returns a result to the main conversation. Use them for research, review, or debugging that would flood the primary session. This Claude Code subagents documentation is a guide to delegation, custom definitions, tool access, and handoff review. Keep ownership and final decisions in the main conversation.

Open the current Claude Code subagents documentation.

Claude Code subagents documentation summary

Create a custom subagent when the same focused task needs the same instructions more than once. Store project definitions in `.claude/agents/` and personal definitions in `~/.claude/agents/`. Use a precise description because Claude uses it for delegation. Restrict tools and permissions, pass only needed context, and define the result the parent should receive.

What are Claude Code subagents?

A subagent is a task-specific Claude assistant inside one Claude Code session. It starts with its own context window, system prompt, tool configuration, and permissions. The parent sends a task, the subagent works independently, and the parent receives the result. Whether someone searches for Claude sub agents or Claude Code subagents, the useful distinction is specialization plus context isolation, not simply another chat tab.

When should you use a subagent?

Codebase research that would return many search results, logs, or file excerpts.
A fresh code review that should not inherit the implementer's reasoning.
A specialist check for accessibility, security, data, performance, or documentation.
A repeatable workflow that needs the same task boundary, tools, and output format.
Parallel independent investigations whose results the parent can reconcile.

When should work stay in the main conversation?

Keep the task in the main conversation when it depends heavily on the full discussion, requires constant user steering, or owns the final integrated change. Delegation adds a handoff. If the task boundary is fuzzy, the summary may lose the detail the parent needs and create more reconciliation work than it saves.

Built-in and custom subagents

Explore: a built-in read-only agent for targeted file discovery, search, and codebase analysis.
Plan: a built-in agent for planning work without implementing the change.
General-purpose and other built-ins: agents Claude can select for suitable work under the current product configuration.
Custom subagent: a named Markdown definition with a description, system prompt, and optional controls for tools, model, permissions, hooks, skills, memory, and isolation.

The live documentation states that, from Claude Code version 2.1.198, `/agents` prints guidance instead of opening the former creation wizard. Ask Claude to create the file or edit the agents directory directly. Older tutorials may still show the removed wizard, so check your installed version and the current official page.

How do you create Claude Code subagents?

Name one repeatable task. Examples include code review, bug diagnosis, dependency research, or interface accessibility review.
Choose the scope. Use the project agents directory for team-owned behavior or the user agents directory for a personal helper.
Create one Markdown file. Put configuration in YAML frontmatter and the working instructions in the Markdown body.
Write a distinctive description. State what the subagent does and the conditions that should trigger delegation.
Allow only required tools. A reviewer normally needs read and search tools, not file writes or unrestricted commands.
Define the output. Ask for evidence, prioritized findings, file references, uncertainty, and a concise handoff to the parent.
Start a new session after manual file edits when the current version requires definitions to reload.
Test explicit invocation on one small task. Inspect the transcript, tool use, output, cost, and value before automatic delegation.
Commit useful project definitions so the team can review and improve them like other configuration.

What belongs in the subagent definition?

Name: a unique identifier that remains clear in delegation and logs.
Description: the task and trigger conditions Claude uses to decide when to delegate.
Tools or denied tools: the smallest capability set that can finish the assignment.
Model: inherit the parent by default or select a current option when cost, speed, or depth justifies it.
Permission mode and MCP scope: explicit access boundaries for commands, files, and connected services.
Skills, hooks, memory, and isolation: optional controls for repeatable knowledge, enforcement, persistence, or worktree separation.
System prompt body: the role, workflow, evidence standard, output shape, and refusal boundary.

Choose the right subagent scope

Project: `.claude/agents/` for repository-specific agents that the team reviews and versions.
User: `~/.claude/agents/` for personal agents available across projects on the machine.
Plugin: the plugin's agents directory for reusable definitions distributed with that plugin.
Managed: organization-controlled definitions with higher precedence.
Session: the current command-line agent configuration for temporary testing or automation.

Automatic and explicit invocation

Claude can delegate automatically when the task matches the subagent description. You can also request a named subagent directly. Start explicit while tuning the definition because the result is easier to evaluate. Once the trigger and output are dependable, automatic delegation can remove repetitive coordination. Foreground work blocks the parent; background work lets independent tasks continue while permission requests return to the main session.

Useful Claude Code subagent patterns

Researcher: read-only search that returns ownership, relevant files, data flow, and unanswered questions.
Reviewer: a fresh context that checks the diff against requirements and reports only material gaps.
Debugger: a bounded reproduce, diagnose, fix, and verify loop with access limited to the affected area.
Accessibility reviewer: checks changed interface code and rendered behavior against specific keyboard, focus, labeling, zoom, contrast, and motion criteria.
Migration worker: handles one independent file or unit under a shared recipe and returns pass, fail, and evidence.
Documentation verifier: compares current product behavior and primary sources against a draft before publication.

Subagent, fork, background agent, or agent team?

Named subagent: fresh context and its own reusable definition inside one session.
Fork: a branch of the current conversation that inherits the parent's history, prompt, tools, and model.
Background agent: an independent session designed for parallel work and monitoring.
Agent team: coordinated sessions that communicate and work from shared tasks.
Main conversation: the place for user steering, integration, accountability, and final handoff.

Common subagent mistakes

A vague specialist: the description overlaps every task, so delegation becomes noisy.
Excessive access: a read-only investigation receives edit, shell, network, or production tools it cannot justify.
Missing output contract: the parent receives a long transcript instead of a decision-ready summary.
Parallel work with shared ownership: agents edit the same files and create conflicts or inconsistent decisions.
Stale instructions: a project pattern changes but the checked-in subagent keeps enforcing the old rule.
Automatic trust: the parent accepts findings or code without verifying sources, commands, tests, or the final diff.

Compare Zenva's context-focused Claude Code subagent tutorial.

Use the broader Claude coding workflow before delegating work.

Frequently asked questions

Named subagents start in a fresh context with their definition and the prompt passed by the parent, not the full conversation history. Built-in and custom types can load different project context under current rules. Check the official startup-context table for the exact type and version.

Independent subagents can run in the background and return results to the main session. Parallel work helps when ownership and inputs do not overlap. Use separate worktrees or independent sessions when several agents need to edit code without collisions.

No. Match the current model to the task's difficulty, latency, and cost. A focused search may use a faster option, while complex review may need deeper reasoning. Keep the model name configurable because the available lineup changes.

Connect Better Design