/subagent-creator

The /subagent-creator skill teaches you how to create effective subagents for specialized tasks.

What are Subagents?

Subagents are specialized Claude instances that:

• Run in isolated contexts with focused roles
• Have limited tool access (configurable)
• Operate autonomously without user interaction
• Return their final output to the main conversation

Quick Start Workflow

1. Run /agents command
2. Select "Create New Agent"
3. Choose project-level (.claude/agents/) or user-level (~/.claude/agents/)
4. Define the subagent configuration
5. Write the system prompt

Example Subagent

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

<role>
You are a senior code reviewer focused on quality, security, and best practices.
</role>

<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>

File Structure

Project-level subagents override user-level when names conflict.

Configuration Fields

name

• Lowercase letters and hyphens only
• Must be unique

description

• Natural language description of purpose
• Include when Claude should invoke this subagent
• Used for automatic subagent selection

tools

• Comma-separated list: Read, Write, Edit, Bash, Grep
• If omitted: inherits all tools from main thread

model

• Options: sonnet, opus, haiku, inherit
• inherit uses the main thread's model

Using the Task Tool

Launch subagents with the Task tool:

Task({
  subagent_type: "code-reviewer",
  prompt: "Review the changes in src/auth/",
  description: "Review auth changes"
})

Background Execution

Running Subagents in Background

Launch agents asynchronously with run_in_background: true:

Task({
  subagent_type: "security-reviewer",
  prompt: "Review all authentication code...",
  run_in_background: true
})

Returns an agent_id for tracking.

Retrieving Results with TaskOutput

TaskOutput({
  task_id: "agent-12345",  // The agent_id from Task call
  block: true,             // Wait for completion (default)
  timeout: 30000           // Max wait time in ms
})

Parallel Execution

Launch multiple agents in a single message for true parallel execution:

// Single message with multiple Task calls
Task({ subagent_type: "code-reviewer", run_in_background: true, ... })
Task({ subagent_type: "security-scanner", run_in_background: true, ... })
Task({ subagent_type: "test-analyzer", run_in_background: true, ... })

When to Use Background

Use for: Long-running analysis, multiple independent tasks, continuing work while waiting

Don't use for: Quick operations (under 10s), sequential dependent tasks, immediate results needed

Best Practices

1. Limit tools - Only give access to what's needed
2. Clear descriptions - Help Claude know when to use it
3. Focused prompts - One purpose per subagent
4. Use model wisely - Haiku for simple tasks, Sonnet for complex