Sub-Agents in Claude Code

Status: Production Ready ✅ Last Updated: 2026-01-14 Source: https://code.claude.com/docs/en/sub-agents

Sub-agents are specialized AI assistants that Claude Code can delegate tasks to. Each sub-agent has its own context window, configurable tools, and custom system prompt.

Why Use Sub-Agents: Context Hygiene

The primary value of sub-agents isn't specialization—it's keeping your main context clean.

Without agent (context bloat):

Main context accumulates: ├─ git status output (50 lines) ├─ npm run build output (200 lines) ├─ tsc --noEmit output (100 lines) ├─ wrangler deploy output (100 lines) ├─ curl health check responses ├─ All reasoning about what to do next └─ Context: 📈 500+ lines consumed

With agent (context hygiene):

Main context: ├─ "Deploy to cloudflare" ├─ [agent summary - 30 lines] └─ Context: 📊 ~50 lines consumed

Agent context (isolated): ├─ All verbose tool outputs ├─ All intermediate reasoning └─ Discarded after returning summary

The math: A deploy workflow runs ~10 tool calls. That's 500+ lines in main context vs 30-line summary with an agent. Over a session, this compounds dramatically.

When this matters most:

Repeatable workflows (deploy, migrate, audit, review) Verbose tool outputs (build logs, test results, API responses) Multi-step operations where only the final result matters Long sessions where context pressure builds up

Key insight: Use agents for workflows you repeat, not just for specialization. The context savings compound over time.

Built-in Sub-Agents

Claude Code includes three built-in sub-agents available out of the box:

Explore Agent

Fast, lightweight agent optimized for read-only codebase exploration.

Property Value Model Haiku (fast, low-latency) Mode Strictly read-only Tools Glob, Grep, Read, Bash (read-only: ls, git status, git log, git diff, find, cat, head, tail)

Thoroughness levels (specify when invoking):

quick - Fast searches, targeted lookups medium - Balanced speed and thoroughness very thorough - Comprehensive analysis across multiple locations

When Claude uses it: Searching/understanding codebase without making changes. Findings don't bloat the main conversation.

User: Where are errors from the client handled? Claude: [Invokes Explore with "medium" thoroughness] → Returns: src/services/process.ts:712

Plan Agent

Specialized for plan mode research and information gathering.

Property Value Model Sonnet Mode Read-only research Tools Read, Glob, Grep, Bash Invocation Automatic in plan mode

When Claude uses it: In plan mode when researching codebase to create a plan. Prevents infinite nesting (sub-agents cannot spawn sub-agents).

General-Purpose Agent

Capable agent for complex, multi-step tasks requiring both exploration AND action.

Property Value Model Sonnet Mode Read AND write Tools All tools Purpose Complex research, multi-step operations, code modifications

When Claude uses it:

Task requires both exploration and modification Complex reasoning needed to interpret search results Multiple strategies may be needed Task has multiple dependent steps Creating Custom Sub-Agents File Locations Type Location Scope Priority Project .claude/agents/ Current project only Highest User ~/.claude/agents/ All projects Lower CLI --agents '{...}' Current session Middle

When names conflict, project-level takes precedence.

⚠️ CRITICAL: Session Restart Required

Agents are loaded at session startup only. If you create new agent files during a session:

They won't appear in /agents Claude won't be able to invoke them Solution: Restart Claude Code session to discover new agents

This is the most common reason custom agents "don't work" - they were created after the session started.

File Format

Markdown files with YAML frontmatter:

name: code-reviewer description: Expert code reviewer. Use proactively after code changes. tools: Read, Grep, Glob, Bash model: inherit permissionMode: default skills: project-workflow hooks: PostToolUse: - matcher: "Edit|Write" hooks: - type: command command: "./scripts/run-linter.sh"

Your sub-agent's system prompt goes here.

Include specific instructions, best practices, and constraints.

Configuration Fields Field Required Description name Yes Unique identifier (lowercase, hyphens) description Yes When Claude should use this agent tools No Comma-separated list. Omit = inherit all tools model No sonnet, opus, haiku, or inherit. Default: sonnet permissionMode No default, acceptEdits, dontAsk, bypassPermissions, plan, ignore skills No Comma-separated skills to auto-load (sub-agents don't inherit parent skills) hooks No PreToolUse, PostToolUse, Stop event handlers Available Tools Reference

Complete list of tools that can be assigned to sub-agents:

Tool Purpose Type Read Read files (text, images, PDFs, notebooks) Read-only Write Create or overwrite files Write Edit Exact string replacements in files Write MultiEdit Batch edits to single file Write Glob File pattern matching (*/.ts) Read-only Grep Content search with regex (ripgrep) Read-only LS List directory contents Read-only Bash Execute shell commands Execute BashOutput Get output from background shells Execute KillShell Terminate background shell Execute Task Spawn sub-agents Orchestration WebFetch Fetch and analyze web content Web WebSearch Search the web Web TodoWrite Create/manage task lists Organization TodoRead Read current task list Organization NotebookRead Read Jupyter notebooks Notebook NotebookEdit Edit Jupyter notebook cells Notebook AskUserQuestion Interactive user questions UI EnterPlanMode Enter planning mode Planning ExitPlanMode Exit planning mode with plan Planning Skill Execute skills in conversation Skills LSP Language Server Protocol integration Advanced MCPSearch MCP tool discovery Advanced

Tool Access Patterns by Agent Type:

Agent Type Recommended Tools Notes Read-only reviewers Read, Grep, Glob, LS No write capability File creators Read, Write, Edit, Glob, Grep ⚠️ No Bash - avoids approval spam Script runners Read, Write, Edit, Glob, Grep, Bash Use when CLI execution needed Research agents Read, Grep, Glob, WebFetch, WebSearch Read-only external access Documentation Read, Write, Edit, Glob, Grep, WebFetch No Bash for cleaner workflow Orchestrators Read, Grep, Glob, Task Minimal tools, delegates to specialists Full access Omit tools field (inherits all) Use sparingly

⚠️ Tool Access Principle: If an agent doesn't need Bash, don't give it Bash. Each bash command requires approval, causing workflow interruptions. See "Avoiding Bash Approval Spam" below.

Avoiding Bash Approval Spam (CRITICAL)

When sub-agents have Bash in their tools list, they often default to using cat > file << 'EOF' heredocs for file creation instead of the Write tool. Each unique bash command requires user approval, causing:

Dozens of approval prompts per agent run Slow, frustrating workflow Hard to review (heredocs are walls of minified content)

Root Causes:

Models default to bash for file ops - Training data bias toward shell commands Bash in tools list = Bash gets used - Even if Write tool is available Instructions get buried - A "don't use bash" rule at line 300 of a 450-line prompt gets ignored

Solutions (in order of preference):

Remove Bash from tools list (if not needed):

Before - causes approval spam

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

After - clean file operations

tools: Read, Write, Edit, Glob, Grep

If the agent only creates files, it doesn't need Bash. The orchestrator can run necessary scripts after.

Put critical instructions FIRST (immediately after frontmatter):

name: site-builder tools: Read, Write, Edit, Glob, Grep model: sonnet

⛔ CRITICAL: USE WRITE TOOL FOR ALL FILES

You do NOT have Bash access. Create ALL files using the Write tool.

[rest of prompt...]

Instructions at the top get followed. Instructions buried 300 lines deep get ignored.

Remove contradictory instructions:

BAD - contradictory

Line 75: "Copy images with cp -r intake/images/* build/images/" Line 300: "NEVER use cp, mkdir, cat, or echo"

GOOD - consistent

Only mention the pattern you want used. Remove all bash examples if you want Write tool.

When to keep Bash:

Agent needs to run external CLIs (wrangler, npm, git) Agent needs to execute scripts Agent needs to check command outputs

Testing: Before vs after removing Bash:

Before (with Bash): 11+ heredoc approval prompts, wrong patterns applied After (no Bash): Mostly Write tool usage, correct patterns, minimal prompts Using /agents Command (Recommended) /agents

Interactive menu to:

View all sub-agents (built-in, user, project) Create new sub-agents with guided setup Edit existing sub-agents and tool access Delete custom sub-agents See which sub-agents are active CLI Configuration claude --agents '{ "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" } }'

Using Sub-Agents Automatic Delegation

Claude proactively delegates based on:

Task description in your request description field in sub-agent config Current context and available tools

Tip: Include "use PROACTIVELY" or "MUST BE USED" in description for more automatic invocation.

Explicit Invocation

Use the test-runner subagent to fix failing tests Have the code-reviewer subagent look at my recent changes Ask the debugger subagent to investigate this error

Resumable Sub-Agents

Sub-agents can be resumed to continue previous conversations:

Initial invocation

Use the code-analyzer agent to review the auth module [Agent completes, returns agentId: "abc123"]

Resume with full context

Resume agent abc123 and now analyze the authorization logic

Use cases:

Long-running research across multiple sessions Iterative refinement without losing context Multi-step workflows with maintained context Disabling Sub-Agents

Add to settings.json permissions:

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

Or via CLI:

claude --disallowedTools "Task(Explore)"

Agent Orchestration

Sub-agents can invoke other sub-agents, enabling sophisticated orchestration patterns. This is accomplished by including the Task tool in an agent's tool list.

How It Works

When a sub-agent has access to the Task tool, it can:

Spawn other sub-agents (built-in or custom) Coordinate parallel work across specialists Chain agents for multi-phase workflows

name: orchestrator description: Orchestrator agent that coordinates other specialized agents. Use for complex multi-phase tasks. tools: Read, Grep, Glob, Task # ← Task tool enables agent spawning model: sonnet

Orchestrator Pattern

name: release-orchestrator description: Coordinates release preparation by delegating to specialized agents. Use before releases. tools: Read, Grep, Glob, Bash, Task

You are a release orchestrator. When invoked:

1. Use Task tool to spawn code-reviewer agent → Review all uncommitted changes

2. Use Task tool to spawn test-runner agent → Run full test suite

3. Use Task tool to spawn doc-validator agent → Check documentation is current

4. Collect all reports and synthesize:

5. Blockers (must fix before release)
6. Warnings (should address)
7. Ready to release: YES/NO

Spawn agents in parallel when tasks are independent. Wait for all agents before synthesizing final report.

Practical Examples

Multi-Specialist Workflow:

User: "Prepare this codebase for production"

orchestrator agent: ├─ Task(code-reviewer) → Reviews code quality ├─ Task(security-auditor) → Checks for vulnerabilities ├─ Task(performance-analyzer) → Identifies bottlenecks └─ Synthesizes findings into actionable report

Parallel Research:

User: "Compare these 5 frameworks for our use case"

research-orchestrator: ├─ Task(general-purpose) → Research framework A ├─ Task(general-purpose) → Research framework B ├─ Task(general-purpose) → Research framework C ├─ Task(general-purpose) → Research framework D ├─ Task(general-purpose) → Research framework E └─ Synthesizes comparison matrix with recommendation

Nesting Depth Level Example Status 1 Claude → orchestrator ✅ Works 2 orchestrator → code-reviewer ✅ Works 3 code-reviewer → sub-task ⚠️ Works but context gets thin 4+ Deeper nesting ❌ Not recommended

Best practice: Keep orchestration to 2 levels deep. Beyond that, context windows shrink and coordination becomes fragile.

When to Use Orchestration Use Orchestration Use Direct Delegation Complex multi-phase workflows Single specialist task Need to synthesize from multiple sources Simple audit or review Parallel execution important Sequential is fine Different specialists required Same agent type Orchestrator vs Direct Delegation

Direct (simpler, often sufficient):

User: "Review my code changes" Claude: [Invokes code-reviewer agent directly]

Orchestrated (when coordination needed):

User: "Prepare release" Claude: [Invokes release-orchestrator] orchestrator: [Spawns code-reviewer, test-runner, doc-validator] orchestrator: [Synthesizes all reports] [Returns comprehensive release readiness report]

Configuration Notes Tool access propagates: An orchestrator with Task can spawn any agent the session has access to Model inheritance: Spawned agents use their configured model (or inherit if set to inherit) Context isolation: Each spawned agent has its own context window Results bubble up: Orchestrator receives agent results and can synthesize them Advanced Patterns Background Agents (Async Delegation)

Send agents to the background while continuing work in your main session:

Ctrl+B during agent execution moves it to background.

Use the research-agent to analyze these 10 frameworks [Agent starts working...] [Press Ctrl+B] → Agent continues in background → Main session free for other work → Check results later with: "What did the research agent find?"

Use cases:

Long-running research tasks Parallel documentation fetching Non-blocking code reviews Model Selection Strategy

Quality-First Approach: Default to Sonnet for most agents. The cost savings from Haiku rarely outweigh the quality loss.

Model Best For Speed Cost Quality sonnet Default for most agents - content generation, reasoning, file creation Balanced Standard ✅ High opus Creative work, complex reasoning, quality-critical outputs Slower Premium ✅ Highest haiku Only for simple script execution where quality doesn't matter 2x faster 3x cheaper ⚠️ Variable inherit Match main conversation Varies Varies Matches parent

Why Sonnet Default?

Testing showed significant quality differences:

Haiku: Wrong stylesheet links, missing CSS, wrong values, incorrect patterns Sonnet: Correct patterns, proper validation, fewer errors Task Type Recommended Model Why Content generation Sonnet Quality matters File creation Sonnet Patterns must be correct Code writing Sonnet Bugs are expensive Audits/reviews Sonnet Judgment required Creative work Opus Maximum quality Deploy scripts Haiku (OK) Just running commands Simple format checks Haiku (OK) Pass/fail only

Pattern: Default Sonnet, use Opus for creative, Haiku only when quality truly doesn't matter:

name: site-builder model: sonnet # Content quality matters - NOT haiku tools: Read, Write, Edit, Glob, Grep

name: creative-director model: opus # Creative work needs maximum quality tools: Read, Write, Edit, Glob, Grep

name: deploy-runner model: haiku # Just running wrangler commands - quality irrelevant tools: Read, Bash

Agent Context Considerations

Agent context usage depends heavily on the task:

Scenario Context Tool Calls Works? Deep research agent 130k 90+ ✅ Yes Multi-file audit 80k+ 50+ ✅ Yes Simple format check 3k 5-10 ✅ Yes Chained orchestration Varies Varies ✅ Depends on task

Reality: Agents with 90+ tool calls and 130k context work fine when doing meaningful work. The limiting factor is task complexity, not arbitrary token limits.

What actually matters:

Is the agent making progress on each tool call? Is context being used for real work vs redundant instructions? Are results coherent at the end?

When context becomes a problem:

Agent starts repeating itself or losing track Results become incoherent or contradictory Agent "forgets" earlier findings in long sessions Persona-Based Routing

Prevent agents from drifting into adjacent domains with explicit constraints:

name: frontend-specialist description: Frontend code expert. NEVER writes backend logic. tools: Read, Write, Edit, Glob, Grep

You are a frontend specialist.

BOUNDARIES: - NEVER write backend logic, API routes, or database queries - ALWAYS use React patterns consistent with the codebase - If task requires backend work, STOP and report "Requires backend specialist"

FOCUS: - React components, hooks, state management - CSS/Tailwind styling - Client-side routing - Browser APIs

This prevents hallucination when agents encounter unfamiliar domains.

Hooks Patterns

Hooks enable automated validation and feedback:

Block-at-commit (enforce quality gates):

hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: | if [[ "$BASH_COMMAND" == "git commit" ]]; then npm test || exit 1 fi

Hint hooks (non-blocking feedback):

hooks: PostToolUse: - matcher: "Edit|Write" hooks: - type: command command: "./scripts/lint-check.sh" # Exits 0 to continue, non-zero to warn

Best practice: Validate at commit stage, not mid-plan. Let agents work freely, catch issues before permanent changes.

Nested CLAUDE.md Context

Claude automatically loads CLAUDE.md files from subdirectories when accessing those paths:

project/ ├── CLAUDE.md # Root context (always loaded) ├── src/ │ └── CLAUDE.md # Loaded when editing src/ ├── tests/ │ └── CLAUDE.md # Loaded when editing tests/ └── docs/ └── CLAUDE.md # Loaded when editing docs/**

Use for: Directory-specific coding standards, local patterns, module documentation.

This is lazy-loaded context - sub-agents get relevant context without bloating main prompt.

Master-Clone vs Custom Subagent

Two philosophies for delegation:

Custom Subagents (explicit specialists):

Main Claude → task-runner agent → result

Pros: Isolated context, specialized prompts, reusable Cons: Gatekeeper effect (main agent loses visibility)

Master-Clone (dynamic delegation):

Main Claude → Task(general-purpose) → result

Pros: Main agent stays informed, flexible routing Cons: Less specialized, may need more guidance

Recommendation: Use custom agents for well-defined, repeated tasks. Use Task(general-purpose) for ad-hoc delegation where main context matters.

Delegation Patterns The Sweet Spot

Best use case: Tasks that are repetitive but require judgment.

✅ Good fit: - Audit 70 skills (repetitive) checking versions against docs (judgment) - Update 50 files (repetitive) deciding what needs changing (judgment) - Research 10 frameworks (repetitive) evaluating trade-offs (judgment)

❌ Poor fit: - Simple find-replace (no judgment needed, use sed/grep) - Single complex task (not repetitive, do it yourself) - Tasks with cross-item dependencies (agents work independently)

Core Prompt Template

This 5-step structure works consistently:

For each [item]: 1. Read [source file/data] 2. Verify with [external check - npm view, API, docs] 3. Check [authoritative source] 4. Evaluate/score 5. FIX issues found ← Critical: gives agent authority to act

Key elements:

"FIX issues found" - Without this, agents only report. With it, they take action. Exact file paths - Prevents ambiguity and wrong-file edits Output format template - Ensures consistent, parseable reports Item list - Explicit list of what to process Batch Sizing Batch Size Use When 3-5 items Complex tasks (deep research, multi-step fixes) 5-8 items Standard tasks (audits, updates, validations) 8-12 items Simple tasks (version checks, format fixes)

Why not more?

Agent context fills up One failure doesn't ruin entire batch Easier to review smaller changesets

Parallel agents: Launch 2-4 agents simultaneously, each with their own batch.

Workflow Pattern ┌─────────────────────────────────────────────────────────────┐ │ 1. PLAN: Identify items, divide into batches │ │ └─ "58 skills ÷ 10 per batch = 6 agents" │ ├─────────────────────────────────────────────────────────────┤ │ 2. LAUNCH: Parallel Task tool calls with identical prompts │ │ └─ Same template, different item lists │ ├─────────────────────────────────────────────────────────────┤ │ 3. WAIT: Agents work in parallel │ │ └─ Read → Verify → Check → Edit → Report │ ├─────────────────────────────────────────────────────────────┤ │ 4. REVIEW: Check agent reports and file changes │ │ └─ git status, spot-check diffs │ ├─────────────────────────────────────────────────────────────┤ │ 5. COMMIT: Batch changes with meaningful changelog │ │ └─ One commit per tier/category, not per agent │ └─────────────────────────────────────────────────────────────┘

Prompt Templates Audit/Validation Pattern Deep audit these [N] [items]. For each:

1. Read the [source file] from [path]
2. Verify [versions/data] with [command or API]
3. Check official [docs/source] for accuracy
4. Score 1-10 and note any issues
5. FIX issues found directly in the file

Items to audit: - [item-1] - [item-2] - [item-3]

For each item, create a summary with: - Score and status (PASS/NEEDS_UPDATE) - Issues found - Fixes applied - Files modified

Working directory: [absolute path]

Bulk Update Pattern Update these [N] [items] to [new standard/format]. For each:

1. Read the current file at [path pattern]
2. Identify what needs changing
3. Apply the update following this pattern: [show example of correct format]
4. Verify the change is valid
5. Report what was changed

Items to update: - [item-1] - [item-2] - [item-3]

Output format:

| Item | Status | Changes Made |

|------|--------|--------------|

Working directory: [absolute path]

Research/Comparison Pattern Research these [N] [options/frameworks/tools]. For each:

1. Check official documentation at [URL pattern or search]
2. Find current version and recent changes
3. Identify key features relevant to [use case]
4. Note any gotchas, limitations, or known issues
5. Rate suitability for [specific need] (1-10)

Options to research: - [option-1] - [option-2] - [option-3]

Output format:

[Option Name]

• Version: X.Y.Z
• Key Features: ...
• Limitations: ...
• Suitability Score: X/10
• Recommendation: ...

Example Custom Sub-Agents Code Reviewer

name: code-reviewer description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. tools: Read, Grep, Glob, Bash model: inherit

You are a senior code reviewer ensuring high standards of code quality and security.

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 implemented - Good test coverage - Performance considerations addressed

Provide feedback organized by priority: - Critical issues (must fix) - Warnings (should fix) - Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger

name: debugger description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. tools: Read, Edit, Bash, Grep, Glob

You are an expert debugger specializing in root cause analysis.

When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works

Debugging process: - Analyze error messages and logs - Check recent code changes - Form and test hypotheses - Add strategic debug logging - Inspect variable states

For each issue, provide: - Root cause explanation - Evidence supporting the diagnosis - Specific code fix - Testing approach - Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Data Scientist

name: data-scientist description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries. tools: Bash, Read, Write model: sonnet

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked: 1. Understand the data analysis requirement 2. Write efficient SQL queries 3. Use BigQuery command line tools (bq) when appropriate 4. Analyze and summarize results 5. Present findings clearly

Key practices: - Write optimized SQL queries with proper filters - Use appropriate aggregations and joins - Include comments explaining complex logic - Format results for readability - Provide data-driven recommendations

Always ensure queries are efficient and cost-effective.

Commit Strategy

Agents don't commit - they only edit files. This is by design:

Agent Does Human Does Research & verify Review changes Edit files Spot-check diffs Score & report git add/commit Create summaries Write changelog

Why?

Review before commit catches agent errors Batch multiple agents into meaningful commits Clean commit history (not 50 tiny commits) Human decides commit message/grouping

Commit pattern:

git add [files] && git commit -m "$(cat <<'EOF' type: [summary]

[Batch 1 changes] [Batch 2 changes] [Batch 3 changes]

🤖 Generated with Claude Code EOF )"

Error Handling When One Agent Fails Check the error message Decide: retry that batch OR skip and continue Don't let one failure block the whole operation When Agent Makes Wrong Change git diff [file] to see what changed git checkout -- [file] to revert Re-run with more specific instructions When Agents Conflict

Rare (agents work on different items), but if it happens:

Check which agent's change is correct Manually resolve or re-run one agent Best Practices Start with Claude-generated agents: Use /agents to generate initial config, then customize Design focused sub-agents: Single, clear responsibility per agent Write detailed prompts: Specific instructions, examples, constraints Don't give Bash unless needed: Prevents approval spam (see "Avoiding Bash Approval Spam") Put critical instructions FIRST: Instructions at top of prompt get followed, buried ones get ignored Remove contradictory instructions: If you want Write tool, remove all bash examples Default to Sonnet model: Quality matters more than cost savings (see Model Selection) Version control: Check .claude/agents/ into git for team sharing Use inherit for model sparingly: Better to explicitly set model for predictable behavior Performance Considerations Consideration Impact Context efficiency Agents preserve main context, enabling longer sessions Latency Sub-agents start fresh, may add latency gathering context Thoroughness Explore agent's thoroughness levels trade speed for completeness Quick Reference Built-in agents: Explore → Haiku, read-only, quick/medium/thorough Plan → Sonnet, plan mode research General → Sonnet, all tools, read/write

Custom agents: Project → .claude/agents/.md (highest priority) User → ~/.claude/agents/.md CLI → --agents '{...}'

Config fields: name, description (required) tools, model, permissionMode, skills, hooks (optional)

Tool access principle: ⚠️ Don't give Bash unless agent needs CLI execution File creators: Read, Write, Edit, Glob, Grep (no Bash!) Script runners: Read, Write, Edit, Glob, Grep, Bash (only if needed) Research: Read, Grep, Glob, WebFetch, WebSearch

Model selection (quality-first): Default: sonnet (most agents - quality matters) Creative: opus (maximum quality) Scripts only: haiku (just running commands) ⚠️ Avoid Haiku for content generation - quality drops significantly

Instruction placement: ⛔ Critical instructions go FIRST (right after frontmatter) ⚠️ Instructions buried 300+ lines deep get ignored ✅ Remove contradictory instructions (pick one pattern)

Delegation: Batch size: 5-8 items per agent Parallel: 2-4 agents simultaneously Prompt: 5-step (read → verify → check → evaluate → FIX)

Orchestration: Enable: Add "Task" to agent's tools list Depth: Keep to 2 levels max Use: Multi-phase workflows, parallel specialists

Advanced: Background: Ctrl+B during agent execution Context: 130k+ and 90+ tool calls work fine for real work Hooks: PreToolUse, PostToolUse, Stop events

Resume agents:

Resume agent [agentId] and continue...

References Official Documentation Sub-Agents Documentation Plugins Documentation Tools Documentation Hooks Documentation CLI Reference Community Resources Awesome Claude Code Subagents - 100+ specialized agents Claude Code System Prompts - Internal prompt analysis Claude Code Built-in Tools Reference - Comprehensive tool guide Claude Code Frameworks Guide (Dec 2025) - Advanced patterns

Last Updated: 2026-01-14