173 lines
5.1 KiB
Markdown
173 lines
5.1 KiB
Markdown
---
|
|
name: sub-agents
|
|
description: How to create and use specialized subagents in Claude Code for task delegation. Use when user asks about creating specialized agents, delegating tasks, agent configuration, or subagent features.
|
|
---
|
|
|
|
# Subagents
|
|
|
|
## Overview
|
|
Subagents are specialized AI assistants that Claude Code can delegate tasks to. Each operates with its own context window, custom system prompt, and configurable tool access.
|
|
|
|
## Key Features
|
|
|
|
**Context Management**: Each subagent operates in its own context, preventing pollution of the main conversation
|
|
|
|
**Specialization**: Task-specific configurations enable higher success rates on designated work
|
|
|
|
**Reusability**: Once created, subagents work across different projects and teams
|
|
|
|
**Flexible Permissions**: Individual tool access control per subagent
|
|
|
|
## Quick Start
|
|
|
|
1. Run `/agents` command
|
|
2. Select "Create New Agent"
|
|
3. Choose project-level or user-level scope
|
|
4. Define purpose, select tools, customize system prompt
|
|
5. Save and invoke automatically or explicitly
|
|
|
|
## Configuration
|
|
|
|
### File Locations
|
|
- **Project subagents**: `.claude/agents/`
|
|
- **User subagents**: `~/.claude/agents/`
|
|
- Project-level takes precedence over user-level
|
|
|
|
### File Format
|
|
Markdown with YAML frontmatter containing:
|
|
- `name`: Unique identifier
|
|
- `description`: Purpose and invocation guidance
|
|
- `tools`: Optional comma-separated list
|
|
- `model`: Optional model alias (sonnet/opus/haiku) or 'inherit'
|
|
|
|
### Example Structure
|
|
```yaml
|
|
---
|
|
name: code-reviewer
|
|
description: Expert code review specialist. Use proactively after code changes.
|
|
tools: Read, Grep, Glob, Bash
|
|
model: inherit
|
|
---
|
|
|
|
Your system prompt explaining the subagent's role and approach...
|
|
```
|
|
|
|
## Available Tools
|
|
|
|
When configuring subagents, you can grant access to these tools via the `tools` field in frontmatter:
|
|
|
|
### Tools That Require Permission
|
|
|
|
**Bash** - Executes shell commands in your environment
|
|
- Use for: Running tests, git commands, build scripts
|
|
- Example: `Bash`
|
|
|
|
**Edit** - Makes targeted edits to specific files
|
|
- Use for: Code modifications, refactoring
|
|
- Example: `Edit`
|
|
|
|
**NotebookEdit** - Modifies Jupyter notebook cells
|
|
- Use for: Data science workflows, notebook updates
|
|
- Example: `NotebookEdit`
|
|
|
|
**SlashCommand** - Runs a custom slash command
|
|
- Use for: Invoking user-defined commands
|
|
- Example: `SlashCommand`
|
|
|
|
**WebFetch** - Fetches content from a specified URL
|
|
- Use for: Documentation lookup, API calls
|
|
- Example: `WebFetch`
|
|
|
|
**WebSearch** - Performs web searches with domain filtering
|
|
- Use for: Finding current information, research
|
|
- Example: `WebSearch`
|
|
|
|
**Write** - Creates or overwrites files
|
|
- Use for: Generating new files, reports
|
|
- Example: `Write`
|
|
|
|
### Tools That Don't Require Permission
|
|
|
|
**Glob** - Finds files based on pattern matching
|
|
- Use for: Finding files by name pattern
|
|
- Example: `Glob`
|
|
|
|
**Grep** - Searches for patterns in file contents
|
|
- Use for: Code search, pattern matching
|
|
- Example: `Grep`
|
|
|
|
**NotebookRead** - Reads and displays Jupyter notebook contents
|
|
- Use for: Analyzing notebooks
|
|
- Example: `NotebookRead`
|
|
|
|
**Read** - Reads the contents of files
|
|
- Use for: Code review, analysis
|
|
- Example: `Read`
|
|
|
|
**Task** - Runs a sub-agent to handle complex, multi-step tasks
|
|
- Use for: Delegating to other specialized agents
|
|
- Example: `Task`
|
|
|
|
**TodoWrite** - Creates and manages structured task lists
|
|
- Use for: Planning and tracking work
|
|
- Example: `TodoWrite`
|
|
|
|
### Configuring Tool Access
|
|
|
|
**Grant all tools:**
|
|
```yaml
|
|
tools: Bash, Edit, Read, Write, Glob, Grep, WebFetch, WebSearch
|
|
```
|
|
|
|
**Grant minimal tools (read-only):**
|
|
```yaml
|
|
tools: Read, Glob, Grep
|
|
```
|
|
|
|
**Grant specific tools for specialized tasks:**
|
|
```yaml
|
|
tools: Read, Bash, TodoWrite # For a test runner agent
|
|
```
|
|
|
|
**Omit tools field to inherit from parent:**
|
|
```yaml
|
|
# No tools field - uses same tools as main Claude instance
|
|
```
|
|
|
|
## Usage Patterns
|
|
|
|
**Automatic Delegation**: Claude recognizes matching tasks and invokes appropriate subagents
|
|
|
|
**Explicit Invocation**: Request specific subagents via natural language commands like "Use the debugger subagent to investigate this error"
|
|
|
|
## Example Subagents
|
|
|
|
### Code Reviewer
|
|
Reviews code for quality, security, and maintainability. Provides feedback categorized by priority (critical/warnings/suggestions).
|
|
|
|
### Debugger
|
|
Specializes in root cause analysis. Captures error messages, isolates failures, and implements minimal fixes.
|
|
|
|
### Data Scientist
|
|
Handles SQL queries and data analysis. Writes optimized queries and provides data-driven recommendations.
|
|
|
|
## Best Practices
|
|
|
|
- Generate initial subagents with Claude, then customize
|
|
- Design focused subagents with single responsibilities
|
|
- Write detailed system prompts with specific instructions
|
|
- Limit tool access to necessary functions only
|
|
- Version control project-level subagents
|
|
|
|
## Advanced Usage
|
|
|
|
**Chaining**: Combine multiple subagents for complex workflows
|
|
|
|
**Dynamic Selection**: Claude intelligently chooses subagents based on task context and description fields
|
|
|
|
**Performance**: Subagents preserve main context but may add latency during initial context gathering
|
|
|
|
## CLI Configuration
|
|
|
|
Define subagents dynamically with `--agents` flag accepting JSON objects for session-specific or automation-based configurations.
|