Skip to content

Article

Subagents

Claude Code Docs

Source ↗ ← All highlights
  • 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
  • Each subagent operates in its own context, preventing pollution of the main conversation and keeping it focused on high-level objectives.
  • • 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

name: your-sub-agent-name description: Description of when this subagent should be invoked tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted model: sonnet # Optional - specify model alias or ‘inherit’

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. Field Required Description name Yes Unique identifier using lowercase letters and hyphens description Yes Natural language description of the subagent’s purpose tools No Comma-separated list of specific tools. If omitted, inherits all tools from the main thread model No Model to use for this subagent. Can be a model alias (sonnet, opus, haiku) or 'inherit' to use the main conversation’s model. If omitted, defaults to the configured subagent model • Model alias: Use one of the available aliases: sonnet, opus, or haiku • 'inherit': Use the same model as the main conversation (useful for consistency) • Omitted: If not specified, uses the default model configured for subagents (sonnet) Using 'inherit' is particularly useful when you want your subagents to adapt to the model choice of the main conversation, ensuring consistent capabilities and response style throughout your session.

  • The /agents command provides a comprehensive interface for subagent management: 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
  • How it works: When you’re in plan mode and Claude needs to understand your codebase to create a plan, it delegates research tasks to the Plan subagent. This prevents infinite nesting of agents (subagents cannot spawn other subagents) while still allowing Claude to gather the necessary context.

  • Example scenario:

    name: code-reviewer description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: inherit

    You are a senior code reviewer ensuring high standards of code quality and security. When invoked:
    1. Run git diff to see recent changes
    2. Focus on modified files
    3. Begin review immediately Review checklist:
    • Code is simple and readable
    • Functions and variables are well-named
    • No duplicated code
    • Proper error handling
    • No exposed secrets or API keys
    • Input validation implemented
    • Good test coverage
    • Performance considerations addressed Provide feedback organized by priority:
    • Critical issues (must fix)
    • Warnings (should fix)
    • Suggestions (consider improving) Include specific examples of how to fix issues.

    name: debugger description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. tools: Read, Edit, Bash, Grep, Glob

    You are an expert debugger specializing in root cause analysis. When invoked:
    1. Capture error message and stack trace
    2. Identify reproduction steps
    3. Isolate the failure location
    4. Implement minimal fix
    5. Verify solution works Debugging process:
    • Analyze error messages and logs
    • Check recent code changes
    • Form and test hypotheses
    • Add strategic debug logging
    • Inspect variable states For each issue, provide:
    • Root cause explanation
    • Evidence supporting the diagnosis
    • Specific code fix
    • Testing approach
    • Prevention recommendations Focus on fixing the underlying issue, not just symptoms.

    name: data-scientist description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries. tools: Bash, Read, Write model: sonnet

    You are a data scientist specializing in SQL and BigQuery analysis. When invoked:
    1. Understand the data analysis requirement
    2. Write efficient SQL queries
    3. Use BigQuery command line tools (bq) when appropriate
    4. Analyze and summarize results
    5. Present findings clearly Key practices:
    • Write optimized SQL queries with proper filters
    • Use appropriate aggregations and joins
    • Include comments explaining complex logic
    • Format results for readability
    • Provide data-driven recommendations For each analysis:
    • Explain the query approach
    • Document any assumptions
    • Highlight key findings
    • Suggest next steps based on data Always ensure queries are efficient and cost-effective.
  • • 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.