Expert guidance for creating, building, and using Claude Code subagents and the Task tool. Use when working with subagents, setting up agent configurations, understanding how agents work, or using the Task tool to launch specialized agents.
Creates specialized subagents with isolated contexts and focused capabilities for complex task delegation.
/plugin marketplace add melvynx/aiblueprint/plugin install base@aiblueprintThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/context-management.mdreferences/debugging-agents.mdreferences/error-handling-and-recovery.mdreferences/evaluation-and-testing.mdreferences/orchestration-patterns.mdreferences/subagents.mdreferences/writing-subagent-prompts.mdSubagents enable delegation of complex tasks to specialized agents that operate autonomously without user interaction, returning their final output to the main conversation. </objective>
<quick_start> <workflow>
/agents command.claude/agents/) or user-level (~/.claude/agents/)sonnet, opus, haiku, or inherit)<focus_areas>
<output_format> Provide specific, actionable feedback with file:line references. </output_format>
</example>
</quick_start>
<file_structure>
| Type | Location | Scope | Priority |
|------|----------|-------|----------|
| **Project** | `.claude/agents/` | Current project only | Highest |
| **User** | `~/.claude/agents/` | All projects | Lower |
| **Plugin** | Plugin's `agents/` dir | All projects | Lowest |
Project-level subagents override user-level when names conflict.
</file_structure>
<configuration>
<field name="name">
- Lowercase letters and hyphens only
- Must be unique
</field>
<field name="description">
- Natural language description of purpose
- Include when Claude should invoke this subagent
- Used for automatic subagent selection
</field>
<field name="tools">
- Comma-separated list: `Read, Write, Edit, Bash, Grep`
- If omitted: inherits all tools from main thread
- Use `/agents` interface to see all available tools
</field>
<field name="model">
- `sonnet`, `opus`, `haiku`, or `inherit`
- `inherit`: uses same model as main conversation
- If omitted: defaults to configured subagent model (usually sonnet)
</field>
</configuration>
<execution_model>
<critical_constraint>
**Subagents are black boxes that cannot interact with users.**
Subagents run in isolated contexts and return their final output to the main conversation. They:
- ✅ Can use tools like Read, Write, Edit, Bash, Grep, Glob
- ✅ Can access MCP servers and other non-interactive tools
- ❌ **Cannot use AskUserQuestion** or any tool requiring user interaction
- ❌ **Cannot present options or wait for user input**
- ❌ **User never sees subagent's intermediate steps**
The main conversation sees only the subagent's final report/output.
</critical_constraint>
<workflow_design>
**Designing workflows with subagents:**
Use **main chat** for:
- Gathering requirements from user (AskUserQuestion)
- Presenting options or decisions to user
- Any task requiring user confirmation/input
- Work where user needs visibility into progress
Use **subagents** for:
- Research tasks (API documentation lookup, code analysis)
- Code generation based on pre-defined requirements
- Analysis and reporting (security review, test coverage)
- Context-heavy operations that don't need user interaction
**Example workflow pattern:**
Main Chat: Ask user for requirements (AskUserQuestion) ↓ Subagent: Research API and create documentation (no user interaction) ↓ Main Chat: Review research with user, confirm approach ↓ Subagent: Generate code based on confirmed plan ↓ Main Chat: Present results, handle testing/deployment
</workflow_design>
</execution_model>
<system_prompt_guidelines>
<principle name="be_specific">
Clearly define the subagent's role, capabilities, and constraints.
</principle>
<principle name="use_pure_xml_structure">
Structure the system prompt with pure XML tags. Remove ALL markdown headings from the body.
```markdown
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: sonnet
---
<role>
You are a senior code reviewer specializing in security.
</role>
<focus_areas>
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization issues
- Sensitive data exposure
</focus_areas>
<workflow>
1. Read the modified files
2. Identify security risks
3. Provide specific remediation steps
4. Rate severity (Critical/High/Medium/Low)
</workflow>
❌ Bad: "You are a helpful assistant that helps with code" ✅ Good: "You are a React component refactoring specialist. Analyze components for hooks best practices, performance anti-patterns, and accessibility issues." </principle> </system_prompt_guidelines>
<subagent_xml_structure> Subagent.md files are system prompts consumed only by Claude. Like skills and slash commands, they should use pure XML structure for optimal parsing and token efficiency.
<recommended_tags> Common tags for subagent structure:
<role> - Who the subagent is and what it does<constraints> - Hard rules (NEVER/MUST/ALWAYS)<focus_areas> - What to prioritize<workflow> - Step-by-step process<output_format> - How to structure deliverables<success_criteria> - Completion criteria<validation> - How to verify work
</recommended_tags><intelligence_rules> Simple subagents (single focused task):
Medium subagents (multi-step process):
Complex subagents (research + generation + validation):
<critical_rule> Remove ALL markdown headings (##, ###) from subagent body. Use semantic XML tags instead.
Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
For XML structure principles and token efficiency details, see @skills/create-agent-skills/references/use-xml-tags.md - the same principles apply to subagents. </critical_rule> </subagent_xml_structure>
<invocation> <automatic> Claude automatically selects subagents based on the `description` field when it matches the current task. </automatic> <explicit> You can explicitly invoke a subagent:> Use the code-reviewer subagent to check my recent changes
> Have the test-writer subagent create tests for the new API endpoints
<background_execution>
Subagents can run in the background using the run_in_background parameter, allowing parallel execution while the main conversation continues.
<how_it_works>
Starting a background subagent:
The Task tool accepts run_in_background: true to launch agents asynchronously:
Task tool call:
- description: "Analyze security vulnerabilities"
- prompt: "Review all authentication code for security issues..."
- subagent_type: "security-reviewer"
- run_in_background: true
The agent starts immediately and returns an agent_id for tracking.
</how_it_works>
<retrieving_results>
Getting results with TaskOutput:
Use the TaskOutput tool to retrieve results from background agents:
TaskOutput tool call:
- task_id: "agent-12345" # The agent_id from the Task call
- block: true # Wait for completion (default)
- timeout: 30000 # Max wait time in ms
Parameters:
| Parameter | Default | Description |
|---|---|---|
task_id | Required | The agent ID returned from Task tool |
block | true | Wait for completion or check current status |
timeout | 30000 | Max wait time in milliseconds (up to 600000) |
Non-blocking check:
Set block: false to check status without waiting:
TaskOutput tool call:
- task_id: "agent-12345"
- block: false
Returns current status: running, completed, or the final result. </retrieving_results>
<parallel_agents> Launching multiple agents in parallel:
To maximize performance, launch multiple independent agents simultaneously:
Single message with multiple Task tool calls:
Task 1:
- description: "Review code quality"
- prompt: "Check code quality..."
- subagent_type: "code-reviewer"
- run_in_background: true
Task 2:
- description: "Run security scan"
- prompt: "Scan for vulnerabilities..."
- subagent_type: "security-scanner"
- run_in_background: true
Task 3:
- description: "Check test coverage"
- prompt: "Analyze test coverage..."
- subagent_type: "test-analyzer"
- run_in_background: true
Then retrieve all results:
TaskOutput calls for each agent_id
</parallel_agents>
<when_to_use_background> Use background agents for:
Don't use background for:
Pattern: Parallel Analysis Pipeline
1. Launch multiple analysis agents in background
2. Continue with other work or wait
3. Collect all results
4. Synthesize findings in main conversation
</when_to_use_background>
<resuming_agents>
Resuming agents:
Agents can be resumed using the resume parameter with their agent ID:
Task tool call:
- description: "Continue security review"
- prompt: "Please continue with the remaining files..."
- subagent_type: "security-reviewer"
- resume: "agent-12345" # Previous agent ID
The agent continues with its full previous context preserved. </resuming_agents> </background_execution>
<management> <using_agents_command> Run `/agents` for an interactive interface to: - View all available subagents - Create new subagents - Edit existing subagents - Delete custom subagents </using_agents_command><manual_editing> You can also edit subagent files directly:
.claude/agents/subagent-name.md~/.claude/agents/subagent-name.md
</manual_editing>
</management>
Subagent usage and configuration: references/subagents.md
Writing effective prompts: references/writing-subagent-prompts.md
Advanced topics:
Evaluation and testing: references/evaluation-and-testing.md
Error handling and recovery: references/error-handling-and-recovery.md
Context management: references/context-management.md
Orchestration patterns: references/orchestration-patterns.md
Debugging and troubleshooting: references/debugging-agents.md
<success_criteria> A well-configured subagent has:
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.