The official Claude Code documentation introduces "subagents," specialized AI assistants designed to improve task-specific workflows and optimize context management within the development environment. These subagents are preconfigured AI personas to which Claude Code can delegate tasks, each operating with a distinct purpose and targeted domain expertise.
Core Characteristics
Each subagent has four essential attributes: an independent context window that avoids polluting the main conversational context, a configurable set of tools specific to its domain, and a customized system prompt guiding its behavior. This contextual isolation enables more focused and effective problem-solving, with fine-tuned instructions improving success rates on designated tasks.
Structural Advantages
Subagents offer four major benefits: context preservation by keeping the main conversation focused on high-level objectives, specialized expertise via detailed instructions for specific domains improving performance, reusability cross-projects with the ability to share across teams promoting consistent workflows, and flexible permissions with granular tool-access control per subagent type for enhanced security.
Creation and Configuration
Creation is initiated via the /agents command in Claude Code, allowing selection between project-level or user-level subagents. Users define the purpose and grant access to specific tools. Subagents are stored as Markdown files with YAML frontmatter: .claude/agents/ for project-level, ~/.claude/agents/ for user-level. Configuration fields include name (unique identifier), description (purpose description), tools (optional comma-separated list), and model (optional specification such as sonnet, opus, haiku, or inherit).
Practical Examples and Patterns
The documentation provides three archetypal examples: Code reviewer, an expert in code quality and security using Read, Grep, Glob, Bash; Debugger, specialized in root cause analysis with Read, Edit, Bash, Grep, Glob; Data scientist, an expert in SQL and BigQuery analysis using Bash, Read, Write. These patterns illustrate how limiting tool access to the strict minimum improves security and focus.
Management and Invocation
The /agents command offers an interactive interface for viewing, creating, editing, deleting subagents, and managing tool permissions. Alternative: direct file management. Claude Code can automatically delegate tasks to subagents based on task description, subagent configuration, and current context. Explicit invocation is possible by mentioning the name.
Best Practices and Advanced Use Cases
Key recommendations include: starting with Claude-generated agents for initial calibration, designing focused subagents with clear responsibilities, writing detailed system prompts, limiting tool access to the strict minimum, and using version control for project subagents. Advanced uses include chaining multiple subagents for complex workflows and leveraging dynamic selection, where Claude automatically chooses the appropriate subagent based on context. This modular architecture enables flexible composition of specialized capabilities while maintaining separation of concerns and contextual clarity.