Claude Code Subagents

Claude Code Subagents

Guide Claude through creating and configuring specialized subagents for Claude Code.

Purpose

Subagents are pre-configured AI personalities that handle specific types of tasks with their own context windows, custom system prompts, and tool configurations. This skill helps create well-structured subagents that improve task delegation, context management, and specialized workflows.

When to Use This Skill

Use this skill when:

• Creating new custom subagents (project, personal, or plugin)
• Configuring subagent properties (tools, model, system prompts)
• Setting up specialized workflows with subagent delegation
• Troubleshooting subagent invocation or behavior

Subagent Types

Project Subagents

• Stored at: .claude/agents/
• Shared with the team (versioned in git)
• Highest priority when name conflicts occur
• Team-specific workflows and conventions

Personal Subagents

• Stored at: ~/.claude/agents/
• Available across all projects
• Lower priority than project subagents
• Personal preferences and workflows

Plugin Subagents

• Stored at: agents/ in plugin root
• Distributed via plugin marketplaces
• Shown as (plugin:plugin-name) in /agents
• Support all configuration features
• Can be invoked explicitly or automatically

Creating Subagents

Quick Creation with Helper Script

Use the bundled creation script for fast, templated subagent setup:

# Create project subagent with code-reviewer template
scripts/create_subagent.sh code-reviewer --project --template code-reviewer

# Create personal subagent with custom template
scripts/create_subagent.sh my-agent --user --template debugger

# Create plugin subagent (auto-detects plugin from current directory)
scripts/create_subagent.sh my-agent --plugin

# Create plugin subagent for specific plugin
scripts/create_subagent.sh my-agent --plugin my-plugin-name

# Available templates: code-reviewer, debugger, custom

The script is located at: scripts/create_subagent.sh

Plugin subagent creation:

• Use --plugin to create subagents in a plugin's agents/ directory
• Auto-detects plugin when run from within a plugin directory
• Or specify plugin name: --plugin my-plugin-name
• Reminds you to register the subagent in marketplace.json

Using the /agents Command

The /agents command provides an interactive interface:

• View all subagents (built-in, user, project, plugin)
• Create new subagents with guided setup
• Generate subagents with Claude's assistance
• Edit custom subagents including tool access
• Delete custom subagents
• See which subagents are active when duplicates exist
• Manage tool permissions easily

Recommended workflow:

1. Run /agents
2. Select 'Create New Agent'
3. Choose scope (project/user)
4. Let Claude generate the subagent based on your description
5. Press e to edit the system prompt in your editor
6. Customize as needed

Manual Creation

When creating subagents manually, follow this structure:

1. Choose scope - Decide between:

   • Project: .claude/agents/
   • Personal: ~/.claude/agents/
   • Plugin: plugins/<plugin-name>/agents/

2. Create directory - Ensure the target directory exists:

   mkdir -p .claude/agents            # Project
   mkdir -p ~/.claude/agents          # Personal
   mkdir -p plugins/my-plugin/agents  # Plugin
   

3. Create file - Named agent-name.md (the filename becomes the agent name)

4. Add frontmatter - Include required fields:

   ---
   name: agent-name
   description: Description of when this subagent should be invoked
   tools: Read, Write, Edit, Bash(git:*)  # Optional; inherits all if omitted
   model: sonnet                          # Optional; sonnet/opus/haiku/inherit
   ---
   

5. Write system prompt - Clear, detailed instructions defining the subagent's role, capabilities, and approach

6. Register plugin subagents - If creating a plugin subagent:

   • Open .claude-plugin/marketplace.json
   • Find the plugin's entry in the plugins array
   • Add "./agents/agent-name.md" to the plugin's agents array

Available Templates

Three templates are provided in assets/ for common use cases:

Code Reviewer (code-reviewer.md)

Senior code reviewer focused on quality, security, and maintainability.

Use when: Need automated code review after changes.

Features:

• Proactive invocation after code modifications
• Comprehensive review checklist
• Priority-based feedback organization
• Security vulnerability detection

Debugger (debugger.md)

Expert debugger for root cause analysis and issue resolution.

Use when: Encountering errors, test failures, or unexpected behavior.

Features:

• Systematic debugging process
• Hypothesis formation and testing
• Strategic logging recommendations
• Root cause identification

Custom Template (custom.md)

Blank template for building specialized subagents.

Use when: Need a starting point for unique workflows.

Configuration Reference

Frontmatter Fields

All available frontmatter fields:

---
name: agent-name                    # Required: lowercase, hyphens only
description: When to invoke agent   # Required: specific, action-oriented
tools: Read, Write, Bash(git:*)    # Optional: comma-separated list
model: sonnet                      # Optional: sonnet/opus/haiku/inherit
---

Field Details

• name (required) - Unique identifier (lowercase, alphanumeric + hyphens)
• description (required) - Natural language description of when the subagent should be invoked
• tools (optional) - Comma-separated list of allowed tools; inherits all if omitted
• model (optional) - Model to use: sonnet, opus, haiku, or inherit (matches conversation model)

Tool Configuration

Subagents can use Claude Code's internal tools. Examples:

# Inherit all tools (including MCP tools)
# Omit the tools field entirely

# Specific tools only
tools: Read, Write, Edit, Grep, Glob

# Bash with patterns
tools: Bash(git:*), Bash(npm:*), Read

# Limited toolset for security
tools: Read, Grep

See full tool list in references documentation.

Workflow

When creating a new subagent:

1. Understand requirements - Ask user about:

   • Subagent purpose and specialization
   • When it should be invoked (automatic vs explicit)
   • What tools it needs access to
   • Scope (project, personal, or plugin)

2. Choose template - Select the most appropriate template:

   • Code-reviewer for code quality checks
   • Debugger for troubleshooting workflows
   • Custom for unique specialized needs

3. Use creation method:

   • Recommended: /agents command for guided setup
   • Script: scripts/create_subagent.sh <name> --<scope> --template <type>
   • Manual: Create file in appropriate directory

4. Customize configuration:

   • Update frontmatter (especially description)
   • Configure tool access if needed
   • Select appropriate model
   • Write clear, detailed system prompt

5. Write effective system prompt:

   • Define the subagent's role and expertise
   • Specify the workflow or process to follow
   • Include success criteria and best practices
   • Add examples if helpful
   • Use imperative/infinitive form (verb-first)

6. Register plugin subagents (plugin scope only):

   • Add subagent to .claude-plugin/marketplace.json
   • In the plugin's entry, add "./agents/<agent-name>.md" to the agents array
   • The script will remind you of this step

7. Test and iterate:

   • Test automatic invocation with matching tasks
   • Test explicit invocation: "Use the X subagent to..."
   • Verify tool access works as expected
   • Adjust description for better delegation
   • Refine system prompt based on results

Invocation Patterns

Automatic Delegation

Claude Code automatically delegates based on:

• Task description matching subagent description
• Context and available tools
• Current conversation needs

Tips for better automatic delegation:

• Use proactive language in description: "Use PROACTIVELY when...", "MUST BE USED for..."
• Be specific about trigger conditions
• Include keywords users are likely to use

Explicit Invocation

Users can request subagents directly:

> Use the code-reviewer subagent to check my recent changes
> Have the debugger subagent investigate this error
> Ask the data-scientist subagent to analyze user growth

Chaining Subagents

For complex workflows:

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

Reference Documentation

For detailed information about subagents, refer to references/subagents-reference.md, which contains:

• Complete subagent architecture details
• File format specification
• Tool permission system
• Model selection guide
• Performance considerations
• Advanced usage patterns
• CLI-based subagent configuration

Load this reference when users need detailed technical information beyond the workflow guidance in this skill.

Best Practices

• Focus on single responsibility - Each subagent should have a clear, specific purpose
• Write detailed system prompts - Include role, process, examples, and constraints
• Use proactive descriptions - Help Claude know when to delegate automatically
• Limit tool access appropriately - Grant only necessary tools for security and focus
• Test both invocation types - Verify automatic and explicit invocation work
• Consider context efficiency - Subagents help preserve main context for longer sessions
• Version control project subagents - Share team workflows via git
• Document expected behavior - Include examples in system prompt when helpful approach that best fits the use case. Subagents and skills can work together—skills can include instructions for when to delegate to specific subagents.