Claude Sub-Agents

View Source

Claude includes a powerful sub-agent system that lets you create specialized AI assistants for specific tasks in your project.

Documentation

For complete documentation on Claude Code's sub-agent system:

What Claude Includes

When you install Claude, you automatically get:

  1. Meta Agent - A built-in agent that helps you create new sub-agents following best practices
  2. Usage Rules Integration - Automatic injection of library best practices into your sub-agents
  3. Project-specific configuration - Sub-agents configured in .claude.exs

Configuration

Sub-agents are configured in .claude.exs:

%{
  subagents: [
    %{
      name: "test-expert",
      role: "ExUnit testing specialist",
      instructions: "You excel at writing comprehensive test suites...",
      usage_rules: ["usage_rules:elixir", "usage_rules:otp"]
    }
  ]
}

Creating Sub-Agents

The easiest way to create a new sub-agent is to ask Claude:

Create a sub-agent for handling GraphQL queries

The Meta Agent will automatically:

  • Generate a complete sub-agent configuration
  • Choose appropriate tools and permissions
  • Include relevant usage rules from your dependencies
  • Add it to your .claude.exs file

Manual Configuration

You can also manually add sub-agents to .claude.exs:

%{
  subagents: [
    %{
      name: "database-specialist",
      role: "Database and Ecto expert",
      instructions: """
      You are an expert in Ecto and database operations.
      
      When invoked, you should:
      1. Analyze the database schema
      2. Write efficient queries
      3. Handle migrations properly
      """,
      tools: [:read, :write, :edit, :bash, :grep],
      usage_rules: ["usage_rules:ecto", "usage_rules:elixir"]
    }
  ]
}

Usage Rules Integration

Sub-agents can automatically include best practices from your dependencies through usage rules:

  • usage_rules:elixir - Elixir language best practices
  • usage_rules:otp - OTP patterns and practices
  • usage_rules:phoenix - Phoenix framework patterns
  • usage_rules:ecto - Database and query best practices
  • And any other dependencies that provide usage rules

Important Notes

  • Clean Slate: Sub-agents start fresh each time - they have no memory of previous interactions
  • Tool Inheritance: When tools are omitted, sub-agents inherit all available tools
  • Performance: Keep instructions focused and context minimal for best performance
  • Delegation: The main Claude agent automatically delegates to sub-agents based on their role descriptions

For more details on sub-agent architecture, delegation patterns, and advanced usage, see the official documentation.