Step 1 of 4Knowledge
The Three Built-in Subagents
Full access to all tools. Can read, write, execute Bash. For complex, multi-step tasks.
Implement feature, write tests, create PR
Can read and execute Bash, but not write. For analysis and planning.
Analyze codebase, create implementation plan
Read-only access. Lean and specialized. For research and navigation.
Find file, search function, check dependencies
Claude Code provides three built-in subagent types that are available without configuration:
1. Explore (inherits model, read-only)
The Explore agent is your fast research assistant. It has only read-only tools such as Read, Grep, Glob, and Bash (read-only); Write and Edit are denied. This makes it ideal for quick codebase searches.
Explore uses the main session's model -- with a subscription or the API, that is usually Opus. (Older guides still mention Haiku here; the current Claude Code documentation is authoritative.) If you want cheaper research, create your own subagent named Explore with model: haiku. It overrides the built-in one:
---
name: Explore
description: Fast, read-only agent for searching and analyzing codebases
model: haiku
---
You are a fast, read-only codebase explorer. Search and analyze code
to answer questions, and do not modify files.
"Find all places where user authentication is called"
Claude Code automatically recognizes this as a research task and delegates it to an Explore subagent. You get a compact summary back -- without your main context being filled with hundreds of files.
2. Plan (inherits model, read-only)
The Plan agent is activated in Plan Mode (Shift+Tab to switch). It inherits the main agent's model but also works in read-only mode. Its job: analyze complex problems and create a structured plan before any code is written.
3. General-purpose (inherits everything)
The General-purpose agent inherits the model, tools, and permissions of the main agent. It's designed for complex subtasks that require both reading and writing -- for example, a refactoring in a specific directory.
Claude Code often decides on its own when a Subagent makes sense. When you ask a question that requires extensive research, an Explore agent is often started automatically. However, you can also request Subagents explicitly.
Creating Custom Agents
Custom Agents are the real game changer. You define them as Markdown files with YAML frontmatter in .claude/agents/:
---
name: code-reviewer
description: Reviews code changes for best practices and potential issues
tools:
- Read
- Grep
- Glob
- Bash
model: sonnet
maxTurns: 20
---
You are an experienced code reviewer. Your task:
1. Read the changed files carefully
2. Check for: error handling, type safety, performance, readability
3. Create a structured review with concrete improvement suggestions
4. Rate the change on a scale of 1-5
Be constructive but thorough. Cite specific line numbers.
Frontmatter Fields in Detail
| Field | Description | Example |
|---|---|---|
name | Unique name of the agent | code-reviewer |
description | Brief description (shown in the agent list) | Reviews code changes |
tools | Allowed tools (whitelist) | [Read, Grep, Glob] |
disallowedTools | Forbidden tools (blacklist) | [Write, Edit] |
model | Model override | haiku, sonnet, opus |
permissionMode | Permission mode | default, plan, bypassPermissions |
maxTurns | Maximum number of tool calls | 20 |
skills | Preloaded Skills (fully injected) | [testing, refactoring] |
mcpServers | Subagent-specific MCP servers | [github, linear] |
memory | Memory scope of the agent | user, project, local |
background | Start as background task | true |
isolation | Isolation mode | worktree |
Use either tools (whitelist) or disallowedTools (blacklist), not both simultaneously. tools is more restrictive and therefore safer for agents that should only read.
Invoking Custom Agents
There are three ways to start a Custom Agent:
1. Natural language -- simply mention it in conversation:
"Use the code-reviewer to check my latest changes"
2. @-Mention -- direct addressing with the agent name:
@"code-reviewer (agent)" check the changes in src/auth/
3. CLI flag -- when starting Claude Code:
claude --agent code-reviewer
If you use an agent frequently, the @-mention syntax is fastest. The CLI flag is suited for automation, for example in Git Hooks or CI/CD pipelines.
Scope Priority
Custom Agents can be defined in different locations. In case of name conflicts, this priority applies (highest first):
- CLI flag (
--agent) -- highest priority - Project agents (
.claude/agents/) -- project-specific, versionable in the repo - User agents (
~/.claude/agents/) -- global for all projects - Plugin agents -- provided by installed plugins
Step 2 of 4Understand
When Custom, When Built-in?
The built-in agents cover most standard cases. Custom Agents are worthwhile when you:
- Have recurring tasks (code review, test creation, documentation)
- Need restricted permissions (an agent that can only read)
- Want to give specific instructions (coding standards, review checklists)
- Want to enforce a specific model (Haiku for simple, Opus for complex tasks)
Think of Custom Agents as templates for recurring delegations. Instead of explaining what the code reviewer should do every time, you define it once -- and invoke it with a single word.
Step 3 of 4Apply
A typical project setup might look like this:
.claude/agents/
reviewer.md # Code review with restricted tools
test-writer.md # Generates tests based on implementation
doc-writer.md # Creates/updates documentation
refactorer.md # Refactoring with specific coding standards
These agents are committed to the repository and available to the entire team. Anyone on the team can trigger the same consistent review process with @"reviewer (agent)".
Step 4 of 4Reflect
The combination of built-in and Custom Agents gives you a flexible toolkit. Built-in agents for everyday tasks, Custom Agents for recurring, specialized tasks. In the next section, we'll look at how Subagents manage their context and how Git Worktrees provide true isolation.