Agent Types & Configuration

Knowledge

The Three Built-in Subagents

Capability level

Click a layer

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. Fast and cheap. 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 (Haiku, read-only)

The Explore agent is your fast research assistant. It runs on the cheaper Haiku model and has only read-only tools: Read, Grep, Glob, and Bash (read-only). This makes it ideal for quick codebase searches.

"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.

iAutomatic Delegation

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`

!tools vs. disallowedTools

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

*Practical Tip

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

Which built-in Subagent is best suited for a quick search for all API endpoints in the project?

Understand

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.

You're creating a Custom Agent for automated test creation. Which configuration makes the most sense?

Apply

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)".

Reflect

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.