Subagent Types

Module: Agents & Subagents | Lesson: 3 of 4 | Time: ~10 minutes

What You Will Learn

• What Explore subagents do (read-only research)
• What Plan subagents do (design before implementing)
• General-purpose and custom subagent types

Prerequisites

• Completed The Agent Tool

Types of Subagents

Not all subagents are the same. Different types of subagents are suited to different kinds of tasks. Understanding these types helps you know what Claude is doing behind the scenes and lets you create your own custom agents.

Explore Agents (Read-Only Research)

What they do: Explore agents investigate your codebase without making any changes. They are read-only — they can read files, search for patterns, and analyze code, but they cannot edit, write, or run commands.

When they are used: Claude spawns explore agents when it needs to understand something before making changes. For example:

• Mapping out how a feature works across multiple files
• Finding all the places a function is called
• Understanding the project structure before suggesting changes

Why read-only matters: Explore agents are safe to use liberally because they cannot accidentally break anything. They gather information and report back.

Example: You ask "How does the payment system work?" Claude might spawn an explore agent to read through the payment-related files, trace the data flow, and return a summary — all without touching any code.

Plan Agents (Design Before Implementing)

What they do: Plan agents analyze a problem and produce a plan — a list of specific changes that need to be made. They do not implement the changes themselves.

When they are used: Claude uses plan agents for complex tasks where jumping straight to implementation would be risky. The plan agent thinks through the approach and produces a detailed plan that Claude (or you) can review before any code is changed.

The plan-then-implement pattern:

1. Plan agent analyzes the task and the codebase
2. Plan agent produces a list of changes needed
3. You review the plan (and can modify it)
4. Claude implements the approved plan

Example: You ask "Refactor the user module to use TypeScript." A plan agent might return:

• Rename user.js to user.ts
• Add type interfaces for User and UserSettings
• Update imports in 5 files that reference the user module
• Add type annotations to 12 functions

You review this plan before Claude makes any changes.

General-Purpose Agents

What they do: General-purpose agents can both read and write. They handle complete subtasks end-to-end, including making changes.

When they are used: When Claude needs to delegate a self-contained piece of work. For example, if you ask Claude to update three unrelated components, it might spawn a general-purpose agent for each one.

Example: You ask "Update the header, footer, and sidebar components to use the new design system." Claude might spawn three agents — one for each component — and each agent handles its component independently.

Creating Custom Agents

You can create your own specialized agents by adding Markdown files to the .claude/agents/ directory. This works similarly to custom skills but specifically defines an agent's behavior and capabilities.

Setting Up the Directory

mkdir -p .claude/agents

Writing a Custom Agent File

Create a Markdown file that defines what the agent does:

---
title: Security Reviewer
description: Reviews code changes for security vulnerabilities
tools:
  - Read
  - Grep
  - Glob
---

# Security Reviewer Agent

You are a security review agent. When invoked, you should:

1. Read all changed files (check git diff)
2. Look for common security issues:
   - SQL injection vulnerabilities
   - Cross-site scripting (XSS) risks
   - Hardcoded secrets or credentials
   - Insecure dependencies
3. For each issue found, report:
   - The file and line number
   - The type of vulnerability
   - A recommended fix
4. If no issues are found, report that the code looks secure.

## Rules
- NEVER modify any files — this is a read-only review
- Check every changed file, not just the obvious ones
- Flag potential issues even if you are not 100% certain

Notice the tools field in the frontmatter — this restricts which tools the agent can use. The Security Reviewer above can only read and search, never edit.

Another Example: Documentation Agent

---
title: Documentation Writer
description: Generates documentation for code changes
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
---

# Documentation Writer Agent

When invoked, you should:

1. Read the recently changed files
2. For each significant change, write or update documentation:
   - Add JSDoc comments to new functions
   - Update the README if the API changed
   - Create or update relevant docs in the docs/ folder
3. Follow the existing documentation style in the project
4. Keep documentation concise and practical

Quick Reference

Agent Type	Can Read	Can Write	Can Run Commands	Best For
Explore	Yes	No	No	Research, understanding code
Plan	Yes	No	No	Designing solutions before implementing
General-Purpose	Yes	Yes	Yes	Complete end-to-end subtasks
Custom	Depends on config	Depends on config	Depends on config	Your specific workflows

Try It Yourself

Create a simple custom agent:

1. Navigate to a project and create the agents directory:

mkdir -p .claude/agents

2. Create a file called .claude/agents/code-reviewer.md:

---
title: Code Reviewer
description: Reviews code for quality and best practices
tools:
  - Read
  - Grep
  - Glob
---

# Code Reviewer Agent

Review code for:
1. Functions longer than 30 lines
2. Missing error handling
3. Unused variables or imports
4. Magic numbers (unexplained numeric literals)

Report each finding with the file name, line number, and a brief explanation.

3. Start Claude Code and ask: "Can you review the code in this project for quality issues?"
4. Claude may use your custom agent (or its own approach) to conduct the review. The agent file provides guidance for how the review should be done.

What You Learned

• Explore agents are read-only — they research and report without making changes
• Plan agents produce a detailed plan before any implementation happens
• General-purpose agents handle complete subtasks including code changes
• You can create custom agents in .claude/agents/ with Markdown files
• Custom agent files define the agent's purpose, allowed tools, and instructions
• Restricting tools (like allowing only Read and Grep) makes agents safer for specific tasks

---

Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up

Next: Plan Mode