Building Subagents

Create production-ready Claude Code subagents through structured research and refinement.

Usage

/building-subagents <agent-name> [options]

Arguments

Agent Name (required):

• Name for the new subagent (kebab-case)

Options:

• --domain DOMAIN: Primary domain (e.g., frontend, backend, security)
• --research-depth LEVEL: quick | medium | thorough (default: medium)
• --output DIR: Output directory (default: .claude/agents/)
• --interactive: Step through creation with prompts

Examples

# Create a new agent
/building-subagents database-migration-agent --domain database

# Quick agent creation
/building-subagents api-testing-agent --research-depth quick

# Interactive mode
/building-subagents security-review-agent --interactive

Workflow

Phase 1: Research

Understand the Domain:

research_prompts = [
    "What are the key responsibilities for a {domain} specialist?",
    "What tools and patterns are commonly used in {domain}?",
    "What are common pitfalls and best practices in {domain}?",
    "What existing agents or patterns could inform this design?"
]

# Research existing agents
existing_agents = glob(".claude/agents/*.md")
relevant_agents = find_similar(existing_agents, domain)

Research Depth Levels:

Level	Actions
quick	Review existing agents, basic domain knowledge
medium	+ Web search for patterns, analyze codebase
thorough	+ Multiple sources, validate with examples

Phase 2: Draft Agent

Agent Structure:

---
name: {agent-name}
description: {Detailed description in third person, including when to use}
tools:
  - {tool1}
  - {tool2}
---

# {Agent Name}

## Role
{Clear definition of agent's purpose and expertise}

## Capabilities
- {Capability 1}
- {Capability 2}

## Guidelines
{Specific instructions for how agent should operate}

## Workflow
{Step-by-step process agent follows}

## Output Format
{Expected output structure}

Description Best Practices:

• Write in third person ("Specializes in..." not "I specialize in...")
• Include "when to use" context
• Be specific about capabilities
• Under 1024 characters

Phase 3: Tool Selection

Select appropriate tools based on agent purpose:

Category	Tools
File operations	Read, Write, Edit, MultiEdit, Glob, Grep
Execution	Bash, Task
Web	WebFetch, WebSearch
PM Integration	pm-context tools
Code analysis	Bash(ast-grep:), Bash(rg:)

Principle of Least Privilege: Only grant tools the agent actually needs.

Phase 4: Refinement

Validation Checks:

• Name follows kebab-case
• Description under 1024 chars
• Description in third person
• Tools are minimal and appropriate
• Guidelines are actionable
• Workflow is clear

Test Scenarios:

test_prompts = [
    "Simple task in domain",
    "Complex multi-step task",
    "Edge case scenario",
    "Error handling scenario"
]

for prompt in test_prompts:
    # Mentally walk through agent's response
    validate_response_quality(agent, prompt)

Phase 5: Output

Write agent file:

.claude/agents/{agent-name}.md

Generate report:

## Subagent Created: {agent-name}

### Summary
- Name: {agent-name}
- Domain: {domain}
- Tools: {tool_count} tools granted

### Description
{agent.description}

### File
{output_path}

### Testing Suggestions
1. Test with: "{test_prompt_1}"
2. Test with: "{test_prompt_2}"

### Integration
Add to Task tool calls:
```python
Task.invoke(
    prompt="...",
    subagent_type="{agent-name}"
)

## Agent Template

```markdown
---
name: {name}
description: {One sentence. What it does and when to use it. Third person. Under 1024 chars.}
tools:
  - Read
  - Glob
  - Grep
  - {additional tools}
---

# {Display Name}

## Role

You are a specialized agent for {domain}. You excel at:
- {Strength 1}
- {Strength 2}
- {Strength 3}

## Guidelines

1. **{Guideline category 1}**
   - {Specific instruction}
   - {Specific instruction}

2. **{Guideline category 2}**
   - {Specific instruction}

## Workflow

1. **Understand**: {What to analyze first}
2. **Plan**: {How to approach the task}
3. **Execute**: {How to perform the work}
4. **Validate**: {How to verify success}
5. **Report**: {What to return to caller}

## Output Format

Return results in this format:

```markdown
## {Task Type} Complete

### Summary
{Brief summary}

### Details
{Detailed findings/results}

### Recommendations
{If applicable}

## Best Practices

1. **Focused purpose** - One agent, one domain
2. **Clear triggers** - Description says when to use
3. **Minimal tools** - Only what's needed
4. **Actionable guidelines** - Specific, not vague
5. **Structured output** - Consistent format