About Claude Code Agents

Custom subagents in Claude Code are specialized AI assistants that can be invoked to handle specific types of tasks. They enable more efficient problem-solving by providing task-specific configurations with customized system prompts, tools and a separate context window.

Subagents are pre-configured AI personalities that Claude Code can delegate tasks to. Each subagent:

• Has a specific purpose and expertise area
• Uses its own context window separate from the main conversation
• Can be configured with specific tools it's allowed to use
• Includes a custom system prompt that guides its behavior

When Claude Code encounters a task that matches a subagent's expertise, it can delegate that task to the specialized subagent, which works independently and returns results.

To create your first subagent:

1. Open the subagents interface

   Run the following command:

   /agents

2. Select 'Create New Agent'

   Choose whether to create a project-level or user-level subagent

3. Define the subagent

   • Recommended: Generate with Claude first, then customize to make it yours
   • Describe your subagent in detail and when it should be used
   • Select the tools you want to grant access to (or leave blank to inherit all tools)
   • The interface shows all available tools, making selection easy
   • If you're generating with Claude, you can also edit the system prompt in your own editor by pressing e

4. Save and use

   Your subagent is now available! Claude will use it automatically when appropriate, or you can invoke it explicitly:

   > Use the code-reviewer subagent to check my recent changes

File locations

Subagents are stored as Markdown files with YAML frontmatter in two possible locations:

When subagent names conflict, project-level subagents take precedence over user-level subagents.

File format

Each subagent is defined in a Markdown file with this structure:

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

Configuration fields

Using the /agents command (Recommended)

The /agents command provides a comprehensive interface for subagent management:

/agents

This opens an interactive menu where you can:

• View all available subagents (built-in, user, and project)
• Create new subagents with guided setup
• Edit existing custom subagents, including their tool access
• Delete custom subagents
• See which subagents are active when duplicates exist
• Easily manage tool permissions with a complete list of available tools

Direct file management

You can also manage subagents by working directly with their files:

# Create a project subagent
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

# Create a user subagent
mkdir -p ~/.claude/agents
# ... create subagent file

Automatic delegation

Claude Code proactively delegates tasks based on:

• The task description in your request
• The description field in subagent configurations
• Current context and available tools

To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your description field.

Explicit invocation

Request a specific subagent by mentioning it in your command:

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

• Start with Claude-generated agents: We highly recommend generating your initial subagent with Claude and then iterating on it to make it personally yours. This approach gives you the best results - a solid foundation that you can customize to your specific needs.
• Design focused subagents: Create subagents with single, clear responsibilities rather than trying to make one subagent do everything. This improves performance and makes subagents more predictable.
• Write detailed prompts: Include specific instructions, examples, and constraints in your system prompts. The more guidance you provide, the better the subagent will perform.
• Limit tool access: Only grant tools that are necessary for the subagent's purpose. This improves security and helps the subagent focus on relevant actions.
• Version control: Check project subagents into version control so your team can benefit from and improve them collaboratively.

Chaining subagents

For complex workflows, you can chain multiple subagents:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Dynamic subagent selection

Claude Code intelligently selects subagents based on context. Make your description fields specific and action-oriented for best results.

• Context efficiency: Agents help preserve main context, enabling longer overall sessions
• Latency: Subagents start off with a clean slate each time they are invoked and may add latency as they gather context that they require to do their job effectively.