Creating Subagents

Creating Subagents

Build specialized AI agents for Claude Code that handle domain-specific tasks with custom configurations, tools, and system prompts.

Quick Reference

What Are Subagents?

Subagents are specialized AI assistants that Claude Code delegates tasks to. They provide:

• Separate Context - Own context window, prevents main conversation pollution
• Custom Tools - Restricted or expanded tool access
• Specialized Prompts - Domain-specific instructions and expertise
• Flexible Models - Can use different models (opus, sonnet, haiku)

When Claude encounters a task matching a subagent's expertise, it spawns the subagent via the Task tool, which works independently and returns results.

Built-in vs Custom Agents

Built-in Agents

Claude Code includes several built-in agents:

When to Create Custom Agents

Create custom agents when you need:

• Domain expertise - Security audit, database migration, API design
• Workflow automation - Test runner, deployment, documentation
• Tool restrictions - Read-only reviewers, sandboxed explorers
• Team consistency - Shared agents for common workflows

Agent Definition Structure

Agents are Markdown files with YAML frontmatter:

---
name: agent-name
description: When this agent should be invoked
tools: Tool1, Tool2, Tool3
model: sonnet
permissionMode: default
skills: skill1, skill2
---

System prompt content here.

Detailed instructions for the agent's behavior,
expertise area, and approach to problem-solving.

Frontmatter Fields

Note on skills: The full skill content is injected into the subagent, not just made available for invocation. Subagents don't inherit skills from the parent conversation.

Model Options

Permission Modes

Subagents inherit permission context from the main conversation but can override the mode.

Important: If the parent uses bypassPermissions, this takes precedence and cannot be overridden by subagents.

Critical Constraint

Subagents cannot spawn other subagents. This prevents infinite nesting. Design your agents to be self-contained.

Hooks in Agent Frontmatter (2.1.0+)

Agents can define hooks scoped to their lifecycle. These hooks are:

• Lifecycle-scoped - Only active while the agent executes
• Auto-cleanup - Removed when the agent finishes
• Portable - Packaged with the agent for distribution

---
name: secure-agent
description: Security-focused agent with audit logging
hooks:
  PreToolUse:
    - matcher: "Bash|Write|Edit"
      hooks:
        - type: command
          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/audit-log.sh"
  Stop:
    - hooks:
        - type: command
          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/agent-complete.sh"
---

Supported hook events in agent frontmatter:

• PreToolUse - Before tool execution
• PostToolUse - After tool completion
• Stop - When agent finishes

Conditional Rules with Hooks

For dynamic control over tool usage, use PreToolUse hooks to validate operations. This is useful when you need to allow some operations of a tool while blocking others.

Example: Read-only database agent

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

The validation script reads JSON from stdin, extracts the command, and exits with code 2 to block:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Hook exit codes:

• 0 - Allow operation
• 2 - Block operation (with message to stderr)

Creating an Agent

Via /agents Command (Recommended)

/agents

Interactive interface to:

• View all available subagents (built-in, user, project, plugin)
• Create new subagents with guided setup or Claude generation
• Edit existing subagent configuration and tool access
• Delete custom subagents
• See active subagents when duplicates exist (higher priority wins)

Generate with Claude: Select "Generate with Claude" and describe your subagent. Claude generates the system prompt and configuration. Press e to open in your editor.

Via File Creation

# Project agent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Run tests and fix failures. Use PROACTIVELY after code changes.
tools: Bash, Read, Glob, Grep, Edit
---

You are a test automation expert.

When invoked:
1. Identify test files related to changes
2. Run appropriate test suite
3. Analyze failures
4. Fix issues while preserving test intent
5. Re-run to verify fixes

Test frameworks to check:
- Jest/Vitest for TypeScript/JavaScript
- pytest for Python
- go test for Go
- cargo test for Rust

Always run tests before reporting completion.
EOF

Via CLI Flag

claude --agents '{
  "test-runner": {
    "description": "Run tests and fix failures",
    "prompt": "You are a test automation expert...",
    "tools": ["Bash", "Read", "Glob", "Grep", "Edit"],
    "model": "sonnet"
  }
}'

Using Agents

Automatic Delegation

Claude automatically delegates based on:

• Task matching description field
• Current context and available tools
• Phrases like "PROACTIVELY" or "MUST BE USED"

Explicit Invocation

> Use the code-reviewer agent to check my changes
> Have the security-audit agent scan for vulnerabilities
> Ask the database-migration agent to create the schema

Chaining Agents

> First use test-runner to find failures, then have debugger fix them

Resuming Agents

Agents can be resumed to continue previous work:

> Resume agent abc123 and continue the analysis

Each execution gets a unique agentId stored in agent-{agentId}.jsonl.

Tool Restrictions

Read-Only Agent

tools: Read, Glob, Grep

Execution-Safe Agent

tools: Bash, Read, Glob, Grep

Note: Bash in this context is still full Bash. For truly safe execution, use hooks to validate commands.

Write-Capable Agent

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

Inherit All Tools

Omit the tools field entirely to inherit all tools from main thread, including MCP tools.

Workflow: Creating a Custom Agent

Prerequisites

• Identify the domain/expertise area
• Determine required tools
• Plan the system prompt

Steps

1. Define the agent

   • Choose descriptive name (lowercase, hyphens)
   • Write clear description with trigger phrases
   • Select minimum necessary tools
   • Choose appropriate model

2. Write system prompt

   • Define role and expertise
   • List step-by-step process
   • Include constraints and best practices
   • Add output format expectations

3. Configure location

   • Project (.claude/agents/) for team sharing
   • User (~/.claude/agents/) for personal use

4. Test

   • Invoke explicitly: "Use the X agent to..."
   • Check /agents menu for registration
   • Verify tool restrictions work

Validation

• Name is lowercase with hyphens
• Description explains when to use
• Tools are minimum necessary
• System prompt is clear and actionable

Priority Order

When agent names conflict, higher priority wins:

Project agents (.claude/agents/) are ideal for team sharing - check them into version control.

User agents (~/.claude/agents/) are personal agents available in all your projects.

CLI agents exist only for that session - useful for quick testing or automation scripts.

Disabling Specific Subagents

Disable built-in or custom subagents using permission rules or CLI flags.

Via settings.json

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

Via CLI

claude --disallowedTools "Task(Explore)"

Permission Rule Syntax

Use Cases

• Security - Prevent delegation to agents with write access
• Workflow control - Force specific agents for certain tasks
• Debugging - Isolate main thread behavior without subagents
• Cost management - Disable expensive opus-based agents

Example: Read-Only Mode

Disable all write-capable agents for safe exploration:

{
  "permissions": {
    "deny": ["Task(general-purpose)", "Task(code-reviewer)"],
    "allow": ["Task(Explore)"]
  }
}

Reference Files