create-subagents

<quick_start>

1. Define the agent's role and when Claude should trigger it
2. Create .claude/agents/agent-name.md (project) or ~/.claude/agents/agent-name.md (personal)
3. Write YAML frontmatter with 5 required fields (name, description, model, color, tools)
4. Write system prompt in the body defining role, process, and output format
5. Test triggering with representative prompts </quick_start>

<essential_principles> Subagents are black boxes. They cannot interact with users. They cannot use AskUserQuestion. The user never sees intermediate steps -- only the final output returned to the main conversation.

Design workflows accordingly:

• Main chat: gather requirements, present options, get confirmation (user interaction)
• Subagent: research, generate, analyze, validate (autonomous work) </essential_principles>

---
name: agent-identifier
description: |
  Use this agent when [specific triggering conditions].

  <example>
  Context: [Situation description]
  user: "[User request]"
  assistant: "[How Claude responds using this agent]"
  <commentary>
  [Why this agent is appropriate for this request]
  </commentary>
  </example>

  <example>
  Context: [Different situation]
  user: "[Different phrasing]"
  assistant: "[Agent response pattern]"
  <commentary>
  [Why agent triggers here too]
  </commentary>
  </example>

model: inherit
color: blue
tools: ["Read", "Grep", "Glob", "Bash"]
---

name (required):

• 3-50 characters, lowercase letters, numbers, and hyphens only
• Must start and end with alphanumeric character
• Must be unique
• Good: code-reviewer, test-generator, api-docs-writer
• Bad: helper (too generic), -agent- (bad chars), my_agent (underscore), ag (too short)

description (required -- most critical field):

• Determines when Claude automatically selects this agent
• MUST include specific triggering conditions
• MUST include 2-4 <example> blocks with context, user request, assistant response, and commentary
• Include both proactive and reactive triggering scenarios
• 200-1,000 characters with examples is the sweet spot

model (required):

• inherit -- uses parent model (recommended default)
• sonnet -- balanced capability and speed (good default for dedicated agents)
• opus -- most capable, use for complex reasoning, architecture decisions
• haiku -- fastest and cheapest, use for simple/repetitive tasks

color (required):

• blue / cyan -- analysis, review, research
• green -- generation, creation, success-oriented
• yellow -- caution, validation, warning
• red -- critical operations, security
• magenta -- creative, generative

tools (optional but recommended):

• Array of tool names: ["Read", "Write", "Grep", "Bash"]
• If omitted: agent inherits ALL tools from main thread
• Apply principle of least privilege -- only grant tools the agent needs
• Common sets:
  • Read-only analysis: ["Read", "Grep", "Glob"]
  • Code generation: ["Read", "Write", "Edit", "Grep"]
  • Testing: ["Read", "Bash", "Grep"] </step_1_frontmatter>

<step_2_system_prompt> Write the body as a system prompt using XML tags (no markdown headings):

<role>
You are [specific role] specializing in [domain].
</role>

<constraints>
- NEVER [dangerous action]
- ALWAYS [required behavior]
- [Other hard rules]
</constraints>

<focus_areas>
- [Priority area 1]
- [Priority area 2]
- [Priority area 3]
</focus_areas>

<workflow>
1. [First step]
2. [Second step]
3. [Third step]
</workflow>

<output_format>
Provide results as:
- [Structure requirement]
- [Content requirement]
- [Formatting requirement]
</output_format>

<success_criteria>
- [Observable completion condition 1]
- [Observable completion condition 2]
</success_criteria>