Creating Subagents Skill

Creating Subagents

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

Quick Reference

| Element | Requirement | |---------|-------------| | Location | .claude/agents/ (project) or ~/.claude/agents/ (user) | | Filename | agent-name.md | | Name | Lowercase, hyphens only (e.g., code-reviewer) | | Required Fields | name, description | | Optional Fields | tools, model, permissionMode, skills, hooks |

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:

| Agent | Model | Mode | Purpose | |-------|-------|------|---------| | Explore | Haiku | Read-only | Fast codebase search and analysis | | Plan | Inherits | Read-only | Research for plan mode | | General-purpose | Inherits | Read/Write | Complex multi-step tasks | | Bash | Inherits | Commands | Running terminal commands in separate context | | statusline-setup | Sonnet | Config | Configuring status line via /statusline | | Claude Code Guide | Haiku | Read-only | Answering questions about Claude Code features |

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

| Field | Required | Type | Description | |-------|----------|------|-------------| | name | Yes | string | Unique identifier (lowercase, hyphens) | | description | Yes | string | When to invoke (include "PROACTIVELY" for auto-use) | | tools | No | string | Comma-separated tool list (allowlist). Omit to inherit all tools | | disallowedTools | No | string | Comma-separated tools to deny (denylist), removed from inherited list | | model | No | string | sonnet, opus, haiku, or inherit | | permissionMode | No | string | Permission handling mode | | skills | No | string | Skills to load into subagent's context at startup | | hooks | No | object | Agent-scoped hooks (2.1.0+) |

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

| Value | Description | |-------|-------------| | sonnet | Default. Balanced capability and speed | | opus | Most capable. Use for complex reasoning | | haiku | Fastest. Use for simple, quick tasks | | inherit | Use main conversation's model |

Permission Modes

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

| Mode | Description | |------|-------------| | default | Standard permission checking with prompts | | acceptEdits | Auto-accept file edits | | dontAsk | Auto-deny permission prompts (explicitly allowed tools still work) | | bypassPermissions | Skip all permission checks (use with caution) | | plan | Plan mode (read-only exploration) |

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

Define the agent
- [ ] Choose descriptive name (lowercase, hyphens)
- [ ] Write clear description with trigger phrases
- [ ] Select minimum necessary tools
- [ ] Choose appropriate model
Write system prompt
- [ ] Define role and expertise
- [ ] List step-by-step process
- [ ] Include constraints and best practices
- [ ] Add output format expectations
Configure location
- [ ] Project (.claude/agents/) for team sharing
- [ ] User (~/.claude/agents/) for personal use
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:

| Priority | Location | Scope | |----------|----------|-------| | 1 (highest) | --agents CLI flag | Current session only | | 2 | .claude/agents/ | Current project | | 3 | ~/.claude/agents/ | All your projects | | 4 (lowest) | Plugin's agents/ directory | Where plugin is enabled |

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

| Pattern | Effect | |---------|--------| | Task(Explore) | Disable built-in Explore agent | | Task(Plan) | Disable built-in Plan agent | | Task(code-reviewer) | Disable custom code-reviewer agent | | Task(*) | Disable all subagents |

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

| File | Contents | |------|----------| | DEFINITION.md | Complete frontmatter reference and file structure | | EXAMPLES.md | Real-world agent examples | | PATTERNS.md | Best practices and composition patterns |

Agent Skills: Creating Subagents

Skill Files