create-subagents

Subagents enable delegation of complex tasks to specialized agents that operate autonomously without user interaction, returning their final output to the main conversation.

<quick_start>

1. Run /agents command
2. Select "Create New Agent"
3. Choose project-level (.claude/agents/) or user-level (~/.claude/agents/)
4. Define the subagent:
   • name: lowercase-with-hyphens
   • description: When should this subagent be used?
   • tools: Optional comma-separated list (inherits all if omitted)
   • model: Optional (sonnet, opus, haiku, or inherit)
5. Write the system prompt (the subagent's instructions)

<focus_areas>

• Code quality and maintainability
• Security vulnerabilities
• Performance issues
• Best practices adherence </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>