Subagent Usage

Authoring

To create or edit subagents, use the agent-kit:claude-agent-development skill.

Philosophy: Proactive Delegation

Use subagents aggressively to preserve main conversation context.

The main agent's context is precious. Every file read, search result, and intermediate reasoning consumes tokens. Subagents run in isolated contexts—when they complete, only their final output returns to the main conversation.

Default stance: If a task can be delegated, delegate it.

When to Delegate

Task arrives
├── Exploration/research? → Explore agent (always)
├── Specialized expertise? → Domain agent
├── Multi-file analysis? → Subagent (saves context)
├── Independent subtask? → Background agent
└── Simple, focused work? → Main agent (maybe)

Delegate when:

• Reading/analyzing more than 2-3 files
• Task requires specialized knowledge (security, performance, testing)
• Work is independent and can run in parallel
• You need to preserve main context for user interaction

Keep in main when:

• Direct user Q&A requiring conversation history
• Single-file, simple operations
• Tasks requiring immediate back-and-forth

Background Invocation

Run agents asynchronously to parallelize work:

{
  "description": "Security audit of auth module",
  "prompt": "Review src/auth/ for vulnerabilities",
  "subagent_type": "security-reviewer",
  "run_in_background": true
}

Retrieve results with TaskOutput:

{
  "task_id": "agent-abc123",
  "block": true
}

Parallel execution pattern:

Main agent receives complex task
  ├─ Launch security-reviewer (background)
  ├─ Launch performance-analyzer (background)
  ├─ Launch test-coverage (background)
  └─ Continue other work...

Later: TaskOutput to collect results
  └─ Synthesize and report to user

Invocation Parameters

Context-Saving Patterns

Research Delegation

{
  "description": "Find auth implementation",
  "prompt": "Locate all authentication-related files and summarize the auth flow",
  "subagent_type": "Explore"
}

Main agent receives summary, not 50 file contents.

Parallel Review

// Launch all in single message with run_in_background: true
{ "subagent_type": "security-reviewer", "run_in_background": true, ... }
{ "subagent_type": "performance-analyzer", "run_in_background": true, ... }
{ "subagent_type": "code-quality", "run_in_background": true, ... }

Three reviews run in parallel. Main agent stays responsive.

Resumable Sessions

{
  "description": "Continue security analysis",
  "prompt": "Now check the session management",
  "subagent_type": "security-reviewer",
  "resume": "abc123"
}

Long analysis across multiple invocations without losing agent context.

Built-in Agents

Design Principles

Generalist over specialist: Few agents (5-7) loading many skills Router pattern: Agents detect task type, load appropriate skill Skill holds methodology: Agent orchestrates, skill executes Context preservation: Main agent stays lean, subagents do heavy lifting

Anti-Patterns

• Reading 10+ files in main agent (delegate to Explore)
• Sequential agent calls that could be parallel
• Keeping research results in main context (let subagent summarize)
• Not using run_in_background for independent tasks