Skip to content

Agent Types & Configuration

  • Claude Code · Module 06
  • Lesson 2 of 4 · then sources and quiz

Step 1 of 4Knowledge

The Three Built-in Subagents

Hierarchy · Capability levelClick 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. 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.

Note
Automatic 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

FieldDescriptionExample
nameUnique name of the agentcode-reviewer
descriptionBrief description (shown in the agent list)Reviews code changes
toolsAllowed tools (whitelist)[Read, Grep, Glob]
disallowedToolsForbidden tools (blacklist)[Write, Edit]
modelModel overridehaiku, sonnet, opus
permissionModePermission modedefault, plan, bypassPermissions
maxTurnsMaximum number of tool calls20
skillsPreloaded Skills (fully injected)[testing, refactoring]
mcpServersSubagent-specific MCP servers[github, linear]
memoryMemory scope of the agentuser, project, local
backgroundStart as background tasktrue
isolationIsolation modeworktree
Warning
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
Tip
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):

  1. CLI flag (--agent) -- highest priority
  2. Project agents (.claude/agents/) -- project-specific, versionable in the repo
  3. User agents (~/.claude/agents/) -- global for all projects
  4. Plugin agents -- provided by installed plugins
Question · Self-check
Which built-in Subagent is best suited for a quick search for all API endpoints in the project?

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.

Question · Self-check
You're creating a Custom Agent for automated test creation. Which configuration makes the most sense?

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.