Subagent Creator

Create specialized subagents that handle specific tasks with their own context windows, system prompts, and tool permissions.

What Are Subagents?

Subagents are mini-agents with:

• Independent context window - Keep exploration out of main conversation
• Custom system prompt - Specialized behavior and expertise
• Scoped tool permissions - Least-privilege access
• Model selection - Cost optimization (Haiku for read-only, Sonnet for complex)

Claude delegates to subagents via the Task tool based on matching descriptions.

Subagent Anatomy

Subagents are Markdown files with YAML frontmatter:

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

You are a senior code reviewer focusing on quality, security, and best practices.

[Instructions for the subagent...]

Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier (lowercase, hyphens allowed)
description	Yes	When Claude should delegate - this is how Claude decides
tools	No	Allowed tools (inherits all if omitted)
disallowedTools	No	Tools to explicitly deny
model	No	haiku, sonnet, opus, or inherit (default: sonnet)
permissionMode	No	default, acceptEdits, dontAsk, bypassPermissions, plan
skills	No	Skills to load at startup
hooks	No	Lifecycle hooks for validation

Storage Locations

Location	Scope	Use Case
.claude/agents/	Current project	Team-shared subagents
~/.claude/agents/	All projects	Personal, reusable subagents
CLI --agents flag	Current session	Quick testing

Model Selection for Cost

Model	Cost	Best For
Haiku	Lowest	Read-only exploration, simple validation
Sonnet	Medium	Most tasks, good balance
Opus	Highest	Complex reasoning, critical decisions
inherit	Parent's	Match main conversation

Permission Modes

permissionMode: default        # Normal permission prompts
permissionMode: acceptEdits    # Auto-accept file edits
permissionMode: dontAsk        # Auto-deny all prompts
permissionMode: bypassPermissions  # Skip all checks (dangerous)
permissionMode: plan           # Read-only exploration mode

Common Tool Sets

Read-only agents:

tools: Read, Grep, Glob

Code review agents:

tools: Read, Grep, Glob, Bash

Full development agents:

tools: Read, Write, Edit, Bash, Grep, Glob

Restricted bash (specific commands only):

tools: Read, Grep, Glob, Bash(git status:*), Bash(git diff:*)

Creation Process

Step 1: Define Purpose

• What specific task does this agent handle?
• What expertise should it have?
• What tools does it need (minimum necessary)?

Step 2: Write Description

The description is how Claude decides when to delegate. Make it specific:

Good: "Expert database query optimizer. Analyzes SQL queries for performance issues, suggests indexes, and rewrites slow queries."

Bad: "Helps with database stuff."

Step 3: Create Agent File

# Project-level (shared with team)
mkdir -p .claude/agents
touch .claude/agents/my-agent.md

# User-level (personal)
mkdir -p ~/.claude/agents
touch ~/.claude/agents/my-agent.md

Step 4: Write Instructions

Use imperative voice. Be specific about:

• What the agent should do when invoked
• How to structure output
• What to avoid
• Error handling

Step 5: Test Delegation

Try prompts that should and shouldn't trigger the agent. Refine description if needed.

Example: Code Reviewer

---
name: code-reviewer
description: Expert code review specialist. Reviews code for quality, security, and maintainability. Use proactively after code changes or when user asks for review.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards.

When invoked:
1. Run `git diff` to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation present
- Good test coverage
- Performance considered

Provide feedback by priority:
- **Critical** (must fix)
- **Warning** (should fix)
- **Suggestion** (consider)

Include specific examples of how to fix issues.

Example: Database Read-Only Agent with Hooks

---
name: db-reader
description: Execute read-only database queries. Use when user needs data analysis without modification risk.
tools: Bash
model: haiku
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly.sh"
---

You are a database analyst with read-only access.
Execute SELECT queries to answer questions about data.

You cannot modify data. If asked to INSERT, UPDATE, DELETE,
or modify schema, explain you only have read access.

Example: Test Runner

---
name: test-runner
description: Run and analyze test suites. Returns only failures and summary, keeping main context clean. Use after code changes or when user asks to run tests.
tools: Bash, Read, Grep
model: haiku
---

You are a test execution specialist.

When invoked:
1. Identify test framework (jest, pytest, vitest, etc.)
2. Run full test suite
3. Analyze failures
4. Return concise summary:
   - Total tests / passed / failed
   - Failed test names and reasons
   - Suggested fixes if obvious

Do NOT include passing test details - only failures matter.

Hooks for Validation

Add validation scripts to enforce constraints:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"

Built-in Subagents

Claude Code includes:

Name	Model	Purpose
Explore	Haiku	Fast, read-only codebase analysis
Plan	Inherited	Research for plan mode
general-purpose	Inherited	Complex multi-step tasks
Bash	Inherited	Terminal commands in isolation

Key Constraints

1. Subagents cannot spawn subagents - Don't include Task in tools
2. Context is isolated - Results must be explicitly returned
3. Tools must be allowed - Can't use tools not in your list
4. Hooks run in order - PreToolUse blocks can reject operations

Common Patterns

1. Isolate High-Volume Operations

Run tests/linting in subagent, return only failures to main conversation.

2. Parallel Research

Multiple subagents explore different aspects, results synthesized by main agent.

3. Cost Optimization

Route read-only tasks to Haiku, complex reasoning to Sonnet/Opus.

4. Security Boundaries

Restrict tools to minimum needed. Use hooks for additional validation.

CLI-Defined Subagents

For quick testing without files:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Troubleshooting

Agent not triggering:

• Check description matches user intent
• Verify file is in correct location
• Check YAML frontmatter syntax

Agent has wrong permissions:

• Explicitly list required tools
• Check disallowedTools doesn't block needed tools

Agent too expensive:

• Use model: haiku for simple tasks
• Scope tools to minimum needed