Create Custom Subagents in Claude Code

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

If you need multiple agents working in parallel and communicating with each other, see agent teams instead. Subagents work within a single session; agent teams coordinate across separate sessions.

Claude Code includes built-in subagents that Claude automatically uses when appropriate:

• Explore — A fast, read-only agent optimized for searching and analyzing codebases. Uses Haiku for speed. Claude delegates to Explore when it needs to search or understand a codebase without making changes. • Plan — A research agent used during plan mode to gather context before presenting a plan. Inherits the main conversation's model. Prevents infinite nesting while still gathering necessary context. • General-purpose — A capable agent for complex, multi-step tasks that require both exploration and action. Has access to all tools. • Other helpers — Bash for terminal commands, statusline-setup for configuring your status line, and Claude Code Guide for answering questions about features.

Subagents are defined in Markdown files with YAML frontmatter. You can create them manually or use the /agents command.

Quickstart walkthrough: 1. Open the subagents interface — Run /agents in Claude Code 2. Create a new user-level agent — Select Create new agent, then choose User-level. This saves to ~/.claude/agents/ so it's available in all your projects. 3. Generate with Claude — Describe the subagent: 'A code improvement agent that scans files and suggests improvements for readability, performance, and best practices.' 4. Select tools — For a read-only reviewer, deselect everything except Read-only tools. 5. Select model — Choose which model the subagent uses. Sonnet balances capability and speed. 6. Choose a color — Pick a background color to identify which subagent is running. 7. Save and try it out — Available immediately, no restart needed.

You can also create subagents manually as Markdown files, define them via CLI flags, or distribute them through plugins.

Subagent scope determines where the agent is available:

• --agents CLI flag — Current session only (highest priority) • .claude/agents/ — Current project, check into version control for team use • ~/.claude/agents/ — All your projects (personal) • Plugin's agents/ directory — Where plugin is enabled (lowest priority)

Subagent files use YAML frontmatter for configuration: • name — Identifier for the subagent • description — How Claude decides when to delegate • model — Which model to use (opus, sonnet, haiku) • tools — Which tools are available (Read, Grep, Glob, Bash, Edit, Write, etc.) • permission-mode — default, plan-mode, or bypass-permissions • skills — Preload specific skills into the subagent • remember — Enable persistent memory across sessions • hooks — Run scripts at specific points in the workflow

Isolate high-volume operations — When tasks read many files (migrations, refactors, audits), delegate to a subagent so the main context stays clean.

Run parallel research — Use subagents to investigate multiple aspects simultaneously. Each returns a focused summary.

Chain subagents — Pass one subagent's output to another. For example, a research agent explores the codebase, then an implementation agent uses the findings.

Choose between subagents and main conversation — Use the main conversation for interactive tasks where you want to guide each step. Use subagents for tasks that can run independently and return results.

Manage subagent context — Subagents can be resumed using their agent ID. Auto-compaction works the same as the main conversation. Keep prompts focused so subagents use their context efficiently.

Code Reviewer — Reviews code for quality, security, and best practices. Uses read-only tools (Read, Grep, Glob, Bash) and the opus model for deeper analysis.

Debugger — Diagnoses and fixes bugs methodically. Has access to all tools including Edit and Write. Follows a systematic approach: reproduce the issue, identify the root cause, implement a fix, and verify.

Data Scientist — Analyzes data, creates visualizations, and builds models. Uses Python-specific tools and can write Jupyter notebooks.

Database Query Validator — Validates SQL queries before execution. Uses hooks to block write operations, ensuring only SELECT queries are allowed. Includes a validation script that checks for INSERT, UPDATE, DELETE, DROP, and other write operations.