./scripts/validate-readonly-query.sh

Skip to main content

Claude Code Docs home page

English

Search...

Ctrl KAsk AI

Search...

Navigation

Build with Claude Code

Create custom subagents

Getting started Build with Claude Code Deployment Administration Configuration Reference Resources

On this page

• Built-in subagents
• Quickstart: create your first subagent
• Configure subagents
• Use the /agents command
• Choose the subagent scope
• Write subagent files
• Supported frontmatter fields
• Choose a model
• Control subagent capabilities
• Available tools
• Permission modes
• Preload skills into subagents
• Conditional rules with hooks
• Disable specific subagents
• Define hooks for subagents
• Hooks in subagent frontmatter
• Project-level hooks for subagent events
• Work with subagents
• Understand automatic delegation
• Run subagents in foreground or background
• Common patterns
• Isolate high-volume operations
• Run parallel research
• Chain subagents
• Choose between subagents and main conversation
• Manage subagent context
• Resume subagents
• Auto-compaction
• Example subagents
• Code reviewer
• Debugger
• Data scientist
• Database query validator
• Next steps

Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent’s description, it delegates to that subagent, which works independently and returns results.Subagents help you:

• Preserve context by keeping exploration and implementation out of your main conversation
• Enforce constraints by limiting which tools a subagent can use
• Reuse configurations across projects with user-level subagents
• Specialize behavior with focused system prompts for specific domains
• Control costs by routing tasks to faster, cheaper models like Haiku

Claude uses each subagent’s description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it.Claude Code includes several built-in subagents like Explore, Plan, and general-purpose. You can also create custom subagents to handle specific tasks. This page covers the built-in subagents, how to create your own, full configuration options, patterns for working with subagents, and example subagents.

​ Built-in subagents

Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation’s permissions with additional tool restrictions.

• Explore

• Plan

• General-purpose

• Other

A fast, read-only agent optimized for searching and analyzing codebases.

• Model: Haiku (fast, low-latency)
• Tools: Read-only tools (denied access to Write and Edit tools)
• Purpose: File discovery, code search, codebase exploration

Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.When invoking Explore, Claude specifies a thoroughness level: quick for targeted lookups, medium for balanced exploration, or very thorough for comprehensive analysis.

A research agent used during plan mode to gather context before presenting a plan.

• Model: Inherits from main conversation
• Tools: Read-only tools (denied access to Write and Edit tools)
• Purpose: Codebase research for planning

When you’re in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent. This prevents infinite nesting (subagents cannot spawn other subagents) while still gathering necessary context.

A capable agent for complex, multi-step tasks that require both exploration and action.

• Model: Inherits from main conversation
• Tools: All tools
• Purpose: Complex research, multi-step operations, code modifications

Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.

Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don’t need to use them directly.

Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents.

​ Quickstart: create your first subagent

Subagents are defined in Markdown files with YAML frontmatter. You can create them manually or use the /agents command.This walkthrough guides you through creating a user-level subagent with the /agent command. The subagent reviews code and suggests improvements for the codebase.

1

Open the subagents interface

In Claude Code, run:

Copy

Ask AI

/agents

2

Create a new user-level agent

Select Create new agent, then choose User-level. This saves the subagent to ~/.claude/agents/ so it’s available in all your projects.

3

Generate with Claude

Select Generate with Claude. When prompted, describe the subagent:

Copy

Ask AI

A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

Claude generates the system prompt and configuration. Press e to open it in your editor if you want to customize it.

4

Select tools

For a read-only reviewer, deselect everything except Read-only tools. If you keep all tools selected, the subagent inherits all tools available to the main conversation.

5

Select model

Choose which model the subagent uses. For this example agent, select Sonnet, which balances capability and speed for analyzing code patterns.

6

Choose a color

Pick a background color for the subagent. This helps you identify which subagent is running in the UI.

7

Save and try it out

Save the subagent. It’s available immediately (no restart needed). Try it:

Copy

Ask AI

Use the code-improver agent to suggest improvements in this project

Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions.

You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements.You can also create subagents manually as Markdown files, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options.

​ Configure subagents

​ Use the /agents command

The /agents command provides an interactive interface for managing subagents. Run /agents to:

• View all available subagents (built-in, user, project, and plugin)
• Create new subagents with guided setup or Claude generation
• Edit existing subagent configuration and tool access
• Delete custom subagents
• See which subagents are active when duplicates exist

This is the recommended way to create and manage subagents. For manual creation or automation, you can also add subagent files directly.

​ Choose the subagent scope

Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.

Project subagents (.claude/agents/) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.User subagents (~/.claude/agents/) are personal subagents available in all your projects.CLI-defined subagents are passed as JSON when launching Claude Code. They exist only for that session and aren’t saved to disk, making them useful for quick testing or automation scripts:

Copy

Ask AI

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

The --agents flag accepts JSON with the same fields as frontmatter. Use prompt for the system prompt (equivalent to the markdown body in file-based subagents). See the CLI reference for the full JSON format.Plugin subagents come from plugins you’ve installed. They appear in /agents alongside your custom subagents. See the plugin components reference for details on creating plugin subagents.

​ Write subagent files

Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

Subagents are loaded at session start. If you create a subagent by manually adding a file, restart your session or use /agents to load it immediately.

Copy

Ask AI

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

The frontmatter defines the subagent’s metadata and configuration. The body becomes the system prompt that guides the subagent’s behavior. Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt.

​ Supported frontmatter fields

The following fields can be used in the YAML frontmatter. Only name and description are required.