Agents Subagents

Claude Code Agents

Create and maintain Claude Code agents/subagents with predictable behavior, least-privilege tools, and explicit delegation contracts.

Quick Start

1. Create an agent file at .claude/agents/<agent-name>.md (kebab-case filename). 2. Add YAML frontmatter (required: name, description; optional: tools, model, permissionMode, skills, hooks). 3. Write the agent prompt: responsibilities, workflow, and an output contract. 4. Minimize tools: start read-only, then add only what the agent truly needs. 5. Test on a real task and iterate.

Minimal template:

---
name: sql-optimizer
description: Optimize SQL queries, explain tradeoffs, and propose safe indexes
tools: Read, Grep, Glob
model: sonnet
---

# SQL Optimizer

## Responsibilities
- Diagnose bottlenecks using query shape and plans when available
- Propose optimizations with risks and expected impact

## Workflow
1. Identify the slow path and data volume assumptions
2. Propose changes (query rewrite, indexes, stats) with rationale
3. Provide a verification plan

## Output Contract
- Summary (1–3 bullets)
- Recommendations (ordered)
- Verification (commands/tests to run)

Workflow (2026)

1. Define the agent’s scope and success criteria. 2. Choose a model based on risk, latency, and cost (default to sonnet for most work). 3. Choose tools via least privilege; avoid granting Edit/Write unless required. 4. If delegating with Task, define a handoff contract (inputs, constraints, output format). 5. Add safety rails for destructive actions and secrets. 6. Add a verification step (checklist, tests, or a dedicated verifier agent).

Frontmatter Fields (Summary)

• name (REQUIRED): kebab-case; match filename (without .md).
• description (REQUIRED): state when to invoke + what it does; include keywords users will say.
• tools (OPTIONAL): explicit allow-list; prefer small, purpose-built sets.
• model (OPTIONAL): haiku for fast checks, sonnet for most tasks, opus for high-stakes reasoning, inherit to match parent.
• permissionMode (OPTIONAL): prefer defaults; change only with a clear reason and understand the tradeoffs.
• skills (OPTIONAL): preload skill packs for domain expertise; keep the list minimal.
• hooks (OPTIONAL): automate guardrails; prefer using the hooks skill for patterns and safety.

For full tool semantics and permission patterns, use references/agent-tools.md. For orchestration and anti-patterns, use references/agent-patterns.md.

2026 Best Practices (Domain Expertise)

• Use small, specialized agents; avoid “god agents”.
• Keep agent prompts short; put repo conventions in CLAUDE.md/project memory and domain knowledge in skills.
• Budget context: pass file paths, minimal snippets, and constraints; avoid dumping long logs/code.
• Use explicit handoffs for subagents: “Goal / Constraints / Inputs / Output Contract”.
• Add a verifier step for risky changes (security, migrations, infra, auth).
• Treat CLI fields/features as moving; verify against official docs in data/sources.json.

Validation Checklist

• Frontmatter: name matches filename; description is single-line and trigger-oriented; tools are minimal; model fits risk.
• Prompt: responsibilities are concrete; workflow is actionable; output contract is explicit.
• Delegation: subagent briefs are specific and bounded; orchestrator verifies integration.
• Safety: confirm destructive ops; avoid secrets/PII; follow repository policies.

Navigation

• frameworks/shared-skills/skills/agents-subagents/references/agent-patterns.md
• frameworks/shared-skills/skills/agents-subagents/references/agent-tools.md
• frameworks/shared-skills/skills/agents-subagents/references/subagent-interruption-recovery.md
• frameworks/shared-skills/skills/agents-subagents/data/sources.json
• frameworks/shared-skills/skills/agents-skills/SKILL.md
• frameworks/shared-skills/skills/agents-hooks/SKILL.md

Subagent Interruption Recovery Protocol

Interruptions are normal in multi-agent runs. Treat them as recoverable state transitions, not total failures.

Recovery Loop

1. Capture partial output from interrupted agent. 2. Classify interruption cause (manual redirect, timeout, context overflow, tool error). 3. Decide resume strategy:

• resume same agent with narrowed scope, or
• spawn replacement agent with explicit handoff from checkpoint.

4. Prevent duplicate work by marking completed subtasks before rerun. 5. Re-verify integration assumptions after recovery.

Required Checkpoint Fields

• completed work
• pending work
• owned files
• unresolved blocker
• next exact command/task

Anti-Pattern

Do not restart full fan-out blindly after one interruption. Resume the smallest affected unit first.

Operational Guardrails: Subagent Orchestration

Use these defaults unless the user explicitly asks for wider fan-out.

Worktree Isolation

For parallel subagent execution, use one Git worktree per agent to prevent file conflicts and index lock contention. See [AI Agent Worktrees](../dev-git-workflow/references/ai-agent-worktrees.md) for setup, directory conventions, safety patterns, and cleanup.

Hard Limits

• Keep active subagents <= 3.
• Keep each subagent scope to one responsibility and a bounded file set.
• Do not let multiple subagents edit the same file in parallel.
• Use one worktree per subagent when running parallel agents locally.

Handoff Template (Standard)

Goal:
Constraints:
Owned files:
Do-not-touch files:
Output format:
Definition of done:

Context-Rich Handoff Template (For Parallel/Swarm Execution)

When dispatching multiple subagents from a plan, front-load each agent with structured context. This reduces token usage, tool calls, and drift.

## Context
- Plan: [plan filename or path]
- Goals: [relevant overview from plan — what this task achieves]
- Dependencies: [prerequisite tasks + their outputs/files]
- Related tasks: [sibling tasks and their function]

## Scope
- Files to create/modify: [full paths]
- Files to read (not modify): [paths for reference only]
- Do-not-touch: [files owned by other agents]

## Acceptance Criteria
- [Criterion 1]
- [Criterion 2]
- [Test/verification command]

## Implementation Steps
1. Read the plan at [path] for full context
2. [Concrete step]
3. [Concrete step]
4. Verify: [specific check]

Why this works: Subagents have no prior context. Without front-loaded detail, they spend tokens rediscovering the codebase. With it, they execute focused work immediately.

Wave Dispatch Protocol

When executing plans with dependency graphs, use waves:

1. Read the dependency graph from the plan. 2. Identify all tasks with no unmet dependencies (Wave 1). 3. Launch one subagent per unblocked task (using context-rich handoff template). 4. Wait for all agents in the wave to complete. 5. Validate each agent's output before proceeding. 6. Identify newly unblocked tasks → launch next wave. 7. Repeat until all tasks complete.

Single-wave shortcut: If only one task is unblocked, launch one agent. Don't force parallelism.

Merge Discipline

1. Wait for subagent outputs. 2. Review for overlap/conflicts. 3. Integrate one subagent result at a time. 4. Run verification gates before final synthesis.

Conflict Resolution (Parallel Outputs)

When parallel agents produce conflicting changes:

1. Detect: Check for overlapping file edits, incompatible interface changes, or divergent assumptions. 2. Prioritize: The agent working on the dependency (upstream task) takes priority for shared interfaces. 3. Resolve: The orchestrator (not subagents) reconciles conflicts — it has the full plan context. 4. Re-run if needed: If conflict resolution invalidates a task's output, re-dispatch that single task with updated context. 5. Document: Record the conflict and resolution in the plan for traceability.

Stop Conditions

Stop and re-plan when:

• two subagents propose conflicting edits to same module,
• repeated retries happen without new evidence,
• context window starts dropping prior decisions,
• conflict resolution would require re-running more than half the completed tasks.

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.

Agent Design Patterns

Detailed patterns for building effective Claude Code agents.

Contents

• Single-Responsibility Agent
• Orchestrator Agent
• Verification Agent
• Pipeline Agent
• Research Agent
• Security Patterns
• Context Management
• Anti-Patterns
• Related

---

Single-Responsibility Agent

Purpose: One agent, one job. Easier to debug, test, and maintain.

Characteristics:

• Focused scope (e.g., "optimize SQL queries" not "handle all database tasks")
• Minimal tool set (only what's needed)
• Clear success criteria
• Predictable behavior

Template:

---
name: sql-optimizer
description: Analyze and optimize SQL queries for performance
tools: Read, Grep, Glob
model: sonnet
---

# SQL Optimizer

You optimize SQL queries. Focus on:

1. Index usage analysis
2. Query plan examination
3. Performance recommendations

Output optimization suggestions with before/after examples.

When to Use:

• Specific, well-defined tasks
• Quality-critical operations (security audits, code reviews)
• Tasks that benefit from deep expertise

---

Orchestrator Agent

Purpose: Coordinate multiple specialized agents. Maintains high-level context while delegating details.

Characteristics:

• Uses Task tool to spawn subagents
• Maintains global plan/state
• Delegates implementation details
• Verifies integration between parts

Template:

---
name: fullstack-builder
description: Coordinate frontend, backend, and database changes
tools: Read, Grep, Glob, Task
model: sonnet
---

# Fullstack Builder

You coordinate multi-layer changes by delegating to specialized agents:

1. Analyze requirements
2. Delegate database changes to sql-engineer
3. Delegate API changes to backend-engineer
4. Delegate UI changes to frontend-engineer
5. Verify integration

## Delegation Guidelines

- Provide clear, specific instructions to each subagent
- Include relevant context (file paths, constraints)
- Verify each agent's output before proceeding

When to Use:

• Multi-step workflows spanning domains
• Feature implementations touching multiple layers
• Complex refactoring across codebase

---

Swarm Orchestrator

Purpose: Execute a plan using parallel subagents dispatched in dependency-aware waves or full parallelism.

Characteristics:

• Reads a plan with a task dependency graph
• Dispatches subagents with context-rich handoff prompts
• Tracks task state: pending → in_progress → completed/failed
• Validates each agent's output before marking done
• Resolves conflicts between parallel outputs

Key responsibilities: 1. Manage plan state (which tasks are done, blocked, or in-progress) 2. Dispatch subagents with full context (plan reference, goals, files, acceptance criteria) 3. Validate subagent work against acceptance criteria 4. Resolve merge conflicts between parallel agents 5. Ensure project moves forward toward plan completion

Template:

---
name: swarm-orchestrator
description: Execute multi-task plans using parallel subagent dispatch with dependency tracking
tools: Read, Grep, Glob, Task, Bash
model: opus
---

# Swarm Orchestrator

Execute the plan by dispatching subagents in waves.

## Workflow

1. Load and parse the plan (task graph, dependencies, file ownership)
2. Identify Wave 1: all tasks with empty depends_on
3. For each unblocked task, dispatch a subagent with:
   - Plan reference and task goals
   - File ownership boundaries
   - Acceptance criteria
   - Implementation steps
4. Wait for wave completion
5. Validate each output (tests, lint, acceptance criteria)
6. Resolve any conflicts between parallel outputs
7. Update plan state, identify next wave
8. Repeat until all tasks complete

## Subagent Prompt Template

For each dispatched subagent, provide:

- Plan: [path to plan file]
- Goals: [what this task achieves in context of the plan]
- Dependencies: [completed prerequisite tasks and their outputs]
- Files to create/modify: [full paths, owned by this agent]
- Do-not-touch: [files owned by other agents]
- Acceptance criteria: [specific, testable conditions]
- Steps: [numbered implementation instructions]

When to Use:

• Executing plans with 3+ independent tasks
• Feature implementations that can be parallelized
• When speed matters but accuracy must be maintained

---

Verification Agent

Purpose: Quality gates. Check work before it proceeds.

Characteristics:

• Read-only (never modifies code)
• Fast (use haiku model)
• Binary output (PASS/FAIL)
• Clear checklist

Template:

---
name: pre-commit-checker
description: Verify code quality before commits
tools: Read, Grep, Bash
model: haiku
---

# Pre-Commit Checker

Run quality checks:

- [ ] Linting passes
- [ ] Tests pass
- [ ] No console.logs
- [ ] No TODO comments
- [ ] Types correct

Return PASS or FAIL with details.

When to Use:

• Pre-commit hooks
• PR review automation
• Continuous integration gates

---

Pipeline Agent

Purpose: Sequential workflow stages with handoffs.

Stages: 1. Spec — Read requirements, write specification 2. Architect — Validate design, produce ADR 3. Implement — Write code and tests 4. Verify — Run checks, update docs

Template:

---
name: feature-pipeline
description: End-to-end feature implementation from spec to deploy
tools: Read, Grep, Glob, Task
model: sonnet
---

# Feature Pipeline

## Stage 1: Specification
Invoke pm-spec agent to analyze requirements.
Status: READY_FOR_ARCH

## Stage 2: Architecture
Invoke architect-review agent to validate design.
Status: READY_FOR_BUILD

## Stage 3: Implementation
Invoke implementer-tester agent to write code.
Status: READY_FOR_VERIFY

## Stage 4: Verification
Run pre-commit-checker agent.
Status: DONE

---

Research Agent

Purpose: Gather information from documentation, web, codebase.

Characteristics:

• Read-only with web access
• Returns structured findings
• Cites sources
• Never modifies code

Template:

---
name: tech-researcher
description: Research technologies, frameworks, and best practices
tools: Read, Grep, Glob, WebFetch, WebSearch
model: sonnet
---

# Technology Researcher

You research technologies and provide structured analysis.

## Output Format

### Summary
[1-2 sentence overview]

### Key Findings
- Finding 1 (source: URL)
- Finding 2 (source: URL)

### Recommendations
- Recommendation 1
- Recommendation 2

### Sources
[List all URLs consulted]

---

Security Patterns

Deny-All Default

# Start with no tools, add only what's needed
tools: Read, Grep  # Read-only by default

Sensitive Action Confirmation

## Before Destructive Actions

1. List what will be changed
2. Ask for confirmation
3. Proceed only with explicit approval

Never run without confirmation:
- git push
- rm -rf
- Database migrations
- Infrastructure changes

Context Isolation

## Context Management

- Each subagent has isolated context
- Orchestrator maintains global state (compact)
- Use CLAUDE.md for shared conventions
- Never pass full codebase to subagents

---

Anti-Patterns

Avoid: God Agent

# BAD: Too many responsibilities
name: do-everything
description: Handle all development tasks
tools: Read, Write, Edit, Bash, WebSearch, Task, ...

Problem: Unpredictable, hard to debug, context bloat.

Avoid: Tool Overload

# BAD: All tools for a read-only task
name: code-reviewer
tools: Read, Write, Edit, Bash, WebSearch, Task

Problem: Security risk, unnecessary permissions.

Avoid: Vague Descriptions

# BAD: Unclear when to invoke
description: Help with code stuff

Problem: Claude can't determine when to use this agent.

---

Related

• agent-tools.md — Tool capabilities reference
• ../SKILL.md — Agent quick reference

Agent Tools Reference

Complete reference for tools available to Claude Code agents.

Contents

• Tool Categories
• Read-Only Tools
• Code Modification Tools
• Execution Tools
• Web Tools
• Delegation Tools
• Tool Permission Patterns
• Security Best Practices
• Tool Selection Checklist
• Related

---

Tool Categories

---

Read-Only Tools

Read

Purpose: Read file contents.

tools: Read

Capabilities:

• Read any file in workspace
• View images (PNG, JPG)
• Parse PDFs (text + visual)
• Read Jupyter notebooks

Example Usage:

Read src/auth/login.ts to understand authentication flow

Always Include: Yes, nearly all agents need this.

---

Grep

Purpose: Search file contents using regex.

tools: Grep

Capabilities:

• Regex pattern matching
• Filter by file type (--type js)
• Filter by glob (--glob "*.tsx")
• Show context lines (-A, -B, -C)

Example Usage:

Search for "TODO|FIXME" in all TypeScript files

Include When: Code analysis, finding patterns, auditing.

---

Glob

Purpose: Find files by name pattern.

tools: Glob

Capabilities:

• Match file paths (**/*.ts)
• Sort by modification time
• Fast even in large codebases

Example Usage:

Find all test files: **/*.test.ts

Include When: File discovery, structure analysis.

---

Code Modification Tools

Edit

Purpose: Modify existing files with precise replacements.

tools: Edit

Capabilities:

• Exact string replacement
• Preserve indentation
• replace_all for bulk changes

Security Note: Only grant to agents that need to modify code.

Example Usage:

Replace deprecated API call with new version

---

Write

Purpose: Create new files or overwrite existing.

tools: Write

Capabilities:

• Create new files
• Overwrite existing files
• Any file type

Security Note: Can overwrite critical files. Use sparingly.

Example Usage:

Create new component file src/components/Button.tsx

---

Execution Tools

Bash

Purpose: Run shell commands.

tools: Bash

Capabilities:

• Run any shell command
• Build projects (npm run build)
• Run tests (pytest, jest)
• Git operations
• Package management

Security Notes:

• Runs with user permissions
• Can execute destructive commands
• Use sandbox mode when possible

Common Commands:

# Build
npm run build
cargo build

# Test
npm test
pytest

# Git
git status
git diff

# Lint
eslint src/
prettier --check .

Include When: Build, test, git, package management needed.

---

Web Tools

WebFetch

Purpose: Fetch and read web page content.

tools: WebFetch

Capabilities:

• Fetch URL content
• Convert HTML to markdown
• Process with AI model
• 15-minute cache

Example Usage:

Fetch React documentation to understand hooks API

Include When: Need to read specific documentation pages.

---

WebSearch

Purpose: Search the web.

tools: WebSearch

Capabilities:

• Web search with query
• Domain filtering (allow/block)
• Returns search results with URLs

Example Usage:

Search for "TypeScript 5.0 new features"

Include When: Research, finding current information.

---

Delegation Tools

Task

Purpose: Spawn subagents for complex work.

tools: Task

Capabilities:

• Launch specialized agents
• Pass prompts to subagents
• Receive results back
• Run multiple agents in parallel

Example Usage:

Delegate security review to security-auditor agent
Delegate API design to backend-engineer agent

Include When: Orchestrator agents that coordinate work.

---

Tool Permission Patterns

Read-Only Agent (Reviewers, Auditors)

tools: Read, Grep, Glob

• Cannot modify code
• Cannot execute commands
• Safe for sensitive codebases

Research Agent

tools: Read, Grep, Glob, WebFetch, WebSearch

• Read-only code access
• Web access for documentation
• Cannot modify anything

Implementation Agent

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

• Full code modification
• Can run builds and tests
• Use for trusted development tasks

Orchestrator Agent

tools: Read, Grep, Glob, Task

• Can spawn subagents
• Limited direct actions
• Delegates implementation

Full-Access Agent (Use Sparingly)

tools: Read, Grep, Glob, Edit, Write, Bash, WebFetch, WebSearch, Task

• All capabilities
• Only for trusted, complex workflows
• Consider splitting into specialized agents

---

Security Best Practices

Principle of Least Privilege

# GOOD: Only what's needed
name: code-reviewer
tools: Read, Grep, Glob

# BAD: Everything "just in case"
name: code-reviewer
tools: Read, Write, Edit, Bash, WebSearch, Task

Dangerous Command Awareness

Commands that should require confirmation:

• rm -rf — Recursive delete
• git push --force — Overwrite history
• sudo — Elevated permissions
• DROP TABLE — Database destruction
• Infrastructure changes

Sandbox Mode

When possible, run in sandbox mode:

• Restricted filesystem access
• Network limitations
• Safer for untrusted operations

---

Tool Selection Checklist

TOOL SELECTION CHECKLIST

[ ] Does agent need to read files? → Read
[ ] Does agent need to search content? → Grep
[ ] Does agent need to find files? → Glob
[ ] Does agent need to modify code? → Edit
[ ] Does agent need to create files? → Write
[ ] Does agent need to run commands? → Bash
[ ] Does agent need web documentation? → WebFetch
[ ] Does agent need to search web? → WebSearch
[ ] Does agent need to delegate work? → Task

Start minimal, add tools only when needed.

---

Related

• agent-patterns.md — Agent design patterns
• ../SKILL.md — Agent quick reference

Subagent Interruption Recovery

Use this guide when parallel agent runs are interrupted or errored mid-execution.

Objective

Recover progress with minimal rework and without restarting unaffected tasks.

Recovery Steps

1. Capture last known output for interrupted agent. 2. Tag interruption reason:

• manual_interrupt
• timeout
• tool_error
• context_overflow

3. Create recovery handoff with:

• what is already done
• what remains
• owned files
• changed assumptions

4. Resume only impacted task, not whole wave. 5. Re-run verification for integration boundaries touched by recovered task.

Decision Matrix

• Resume same agent when context is still valid and scope is narrow.
• Spawn replacement agent when previous context is noisy or ownership changed.
• Escalate to orchestrator-only fix when multiple agents now conflict on shared interfaces.

Tracking

Maintain an interruption ledger per wave:

• agent id
• task id
• cause
• recovery action
• final status