Cookies

With your permission, we use Google Analytics cookies to measure visits and improve the site. Necessary cookies are always on. You can change your choice or withdraw consent anytime in the footer, under Cookie settings. Cookie Policy

Skip to content
PTEN
Get started

Subagents - Complete Reference Guide

IntermediatePro38 minupdated 2026-10-21

Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each subagent has a specific purpose, uses its own context window separate from the main conversation, and can be configured with specific tools and a custom system prompt.

Table of Contents

  1. Overview
  2. Key Benefits
  3. File Locations
  4. Configuration
  5. Built-in Subagents
  6. Managing Subagents
  7. Using Subagents
  8. Resumable Agents
  9. Chaining Subagents
  10. Persistent Memory for Subagents
  11. Background Subagents
  12. Worktree Isolation
  13. Forked Subagents
  14. Restrict Spawnable Subagents
  15. claude agents CLI Command
  16. Agent Teams (Experimental)
  17. Plugin Subagent Security
  18. Architecture
  19. Context Management
  20. When to Use Subagents
  21. Best Practices
  22. Example Subagents in This Folder
  23. Installation Instructions
  24. File Structure
  25. Related Concepts
  26. Observability
  27. Additional Resources

Overview

Subagents enable delegated task execution in Claude Code by:

  • Creating isolated AI assistants with separate context windows
  • Providing customized system prompts for specialized expertise
  • Enforcing tool access control to limit capabilities
  • Preventing context pollution from complex tasks
  • Enabling parallel execution of multiple specialized tasks

Each subagent operates independently with a clean slate, receiving only the specific context necessary for their task, then returning results to the main agent for synthesis.

Quick Start: Ask Claude to create a subagent for you ("create a subagent that reviews security"), or add a .claude/agents/<name>.md file directly - see Managing Subagents below.

This guide continues on the Pro plan

You have seen the introduction and the first example. With Pro you unlock this guide and every other one - updated every day, with ready-to-copy examples.

In this guide (Pro): Key Benefits · File Locations · Configuration · Built-in Subagents · Managing Subagents · Using Subagents · Resumable Agents · Chaining Subagents · Persistent Memory for Subagents · Background Subagents · Worktree Isolation · Forked Subagents · Restrict Spawnable Subagents · `claude agents` CLI Command · Agent Teams (Experimental) · Plugin Subagent Security · Architecture · Context Management · When to Use Subagents · Best Practices · Example Subagents in This Folder · Installation Instructions · File Structure · Related Concepts · Observability · Additional Resources

€7.99/month · No commitment · Cancel anytime

Examples and resources for this module

  • Clean Code Reviewer Agent

    Clean Code principles enforcement specialist. Reviews code for violations of Clean Code theory and best practices. Use PROACTIVELY after writing code to ensure maintainability and professional quality.

    2 min

  • Code Reviewer Agent

    Expert code review specialist. Use PROACTIVELY after writing or modifying code to ensure quality, security, and maintainability.

    2 min

  • Data Scientist Agent

    Data analysis expert for SQL queries, BigQuery operations, and data insights. Use PROACTIVELY for data analysis tasks and queries.

    2 min

  • Debugger Agent

    Debugging specialist for errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering any issues.

    2 min

  • Implementation Agent

    Full-stack implementation specialist for feature development. Has complete tool access for end-to-end implementation.

    2 min

  • Performance Optimizer Agent

    Performance analysis and optimization specialist. Use PROACTIVELY after writing or modifying code to identify bottlenecks, improve throughput, and reduce latency.

    4 min

  • Secure Code Reviewer

    Security-focused code review specialist with minimal permissions. Read-only access ensures safe security audits.

    2 min

  • Test Engineer Agent

    Test automation expert for writing comprehensive tests. Use PROACTIVELY when new features are implemented or code is modified.

    2 min

Open-source community guide (MIT) · curated and maintained by Doutor AI.

Need a tailor-made solution?

Not sure where to start with AI in your business? Get a free assessment and a tailored plan - no commitment.

Save hours every week with AI, no hassle

Doutor AI gives you 1,859 ready-to-copy AI prompts, by industry and in plain English - plus a complete technical library for those who want to go further.

See plans