subagent-engineering

Subagent Engineering

Manage the full lifecycle of Claude Code subagents: creation, evaluation, iteration, and troubleshooting.

**Subagent prompts are system prompts.** Before creating or improving a subagent, invoke `prompt-engineering` to load instruction design techniques.

Skill(ai-helpers:prompt-engineering)

Skip only for trivial edits (typos, formatting).

Route to Reference

• Full frontmatter field reference — [${CLAUDE_SKILL_DIR}/references/spec.md] All fields with constraints, hooks schema, CLI-defined agents, storage locations
• Step-by-step creation walkthrough — [${CLAUDE_SKILL_DIR}/references/creation.md] Detailed process, common agent type templates, proactive delegation
• Quality scoring and testing — [${CLAUDE_SKILL_DIR}/references/evaluation.md] 5-dimension scoring rubric with weights, testing protocol (5 levels), benchmarking
• Improving an existing subagent — [${CLAUDE_SKILL_DIR}/references/iteration.md] Prompt refinement techniques, A/B testing, version control, redesign criteria
• Diagnosing failures — [${CLAUDE_SKILL_DIR}/references/troubleshooting.md] Diagnostic steps, error message catalog, debug mode
• Architecture and examples — [${CLAUDE_SKILL_DIR}/references/patterns.md] Full agent examples, pipeline/parallel/master-clone patterns, multi-agent coordination, agent team lifecycle and patterns

Read the relevant reference for extended depth. The rules below are sufficient for correct work without loading references.

When to Use Subagents

Use subagents when:

• Task produces verbose output you don't need in main context
• You want to enforce specific tool restrictions
• Work is self-contained and can return a summary
• You need to parallelize independent research

Use main conversation when:

• Task needs frequent back-and-forth
• Multiple phases share significant context
• Making quick, targeted changes
• Latency matters (subagents start fresh)

Use skills instead when:

• You want reusable prompts in main conversation context
• Task benefits from full conversation history

Subagent File Format

.claude/agents/my-agent.md    # Project-level
~/.claude/agents/my-agent.md  # User-level

---
name: my-agent
description: What it does. When to use it.
tools: Read, Grep, Glob
model: sonnet
---

You are a [role]. When invoked:
1. [First step]
2. [Second step]
3. [Final output format]

Scope Priority (highest to lowest)

1. --agents CLI flag (session only)
2. .claude/agents/ (project)
3. ~/.claude/agents/ (user)
4. Plugin agents (lowest)

When names collide, higher priority wins.

Required Frontmatter Fields

name

• Lowercase letters, numbers, hyphens only
• Max 64 characters, no < or > characters
• Cannot contain "anthropic" or "claude"
• Must match filename (minus .md)

description

Claude sees ONLY name and description when deciding to delegate. The body loads AFTER delegation. This makes the description the highest-leverage field.

Formula:

[What it does in 1 sentence]. [When to use it — specific trigger context].

Rules:

• Lead with what the agent does, not a slogan or tagline.
• State when to use it — specific contexts and trigger conditions.
• Include "use proactively" to encourage automatic delegation.
• Keep execution instructions out of the description — those belong in the body.
• No keyword lists, no second person ("you can..."), no vague verbs ("helps", "assists").
• Max 1024 characters, no < or > characters.

Good:

description: "Expert code review specialist. Proactively reviews code for
  quality, security, and maintainability. Use immediately after writing
  or modifying code."

description: "PostgreSQL database expert for query optimization and schema
  design. Use when working with .sql files or database performance issues."

Bad:

description: "Helps with code"                    # Too vague
description: "Review code. Steps: 1. Read 2..."   # Execution details
description: "Code review. Keywords: review..."    # Keyword stuffing

Optional Frontmatter Fields

tools

Allowlist of tools the subagent can use. If omitted, inherits ALL tools from the main conversation (including MCP tools). Be intentional — don't leave it blank unless you want full access.

Principle: grant minimum necessary permissions.

• Read-only (reviewers, analysts): Read, Grep, Glob
• Research (with web): Read, Grep, Glob, WebFetch, WebSearch
• Code writers: Read, Write, Edit, Bash, Glob, Grep
• Documentation: Read, Write, Edit, Glob, Grep, WebFetch

Available built-in tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task (main agent only), NotebookEdit.

Use disallowedTools when you want most tools but need to exclude a few.

model

• haiku: Quick searches, docs, simple analysis — fast and cheap
• sonnet: Everyday coding, debugging, refactoring
• opus: Architecture decisions, security audits, complex reasoning
• inherit: Match parent model (default if omitted)

permissionMode

• default: Standard permission checking
• acceptEdits: Auto-accept file edits
• dontAsk: Auto-deny prompts (allowed tools still work)
• bypassPermissions: Skip all permission checks
• plan: Plan mode (read-only exploration)

Security rules:

• Prefer plan mode for read-only agents — enforce safety at the permission level, not just in the prompt.
• bypassPermissions skips ALL checks including file writes and command execution. Only use for trusted, well-tested agents.
• If parent uses bypassPermissions, child agents inherit it and cannot override to a more restrictive mode.

skills

Skills to inject into the subagent's context at startup. Subagents don't inherit skills from parent — list them explicitly.

skills:
  - api-conventions
  - error-handling-patterns

hooks

Lifecycle hooks scoped to this subagent. Supported events: PreToolUse, PostToolUse, Stop (converted to SubagentStop).

Full hook schema and examples: see ${CLAUDE_SKILL_DIR}/references/spec.md.

Writing the System Prompt

Everything after the frontmatter becomes the subagent's system prompt. Subagents receive ONLY this prompt plus basic environment details — not the full Claude Code system prompt.

Structure Template

You are a [role] specializing in [domain].

## When Invoked
1. [First action]
2. [Second action]
3. [Continue until complete]

## Guidelines
- [Guideline 1]
- [Guideline 2]

## Constraints
- [Boundary 1 — what NOT to do]

## Output Format
[Specify exact structure with example]

System Prompt Rules

• Start with role definition. "You are a [role] specializing in [domain]."
• Use numbered steps for workflow. Explicit ordering prevents skipped steps.
• Specify output format explicitly. Include a concrete example of the expected output structure.
• Add constraints to prevent scope creep. "DO NOT modify files", "ONLY report findings", "ASK for clarification if unclear."
• Include checklists for consistency. Agents follow checklists more reliably than prose guidelines.
• Add completion criteria. "Your task is COMPLETE when: [criteria]." Prevents both early termination and over-work.
• Keep single responsibility. If listing multiple unrelated capabilities, split into separate agents.
• Add efficiency instructions. "Use Grep to locate relevant code BEFORE reading entire files. Return concise summaries, not raw data."

Core Design Principles

• Description is the trigger. Claude sees ONLY name + description when deciding to delegate. Vague descriptions cause wrong triggers. Specific descriptions enable correct delegation.

• Single responsibility. Each subagent excels at ONE task. Don't create Swiss Army knife agents — they're hard to trigger correctly and mediocre at everything.

• Minimal tool access. Grant only necessary permissions. Read-only agents don't need Edit/Write. Excess tools invite scope creep.

• Clear handoffs. Design subagents to return actionable summaries, not raw data dumps. The parent agent (or user) should be able to act on the output immediately.

• Context efficiency. Subagents should use Grep before Read, stop when they have enough information, and return synthesized findings. Verbose returns consume parent context.

Built-in Subagents

• Explore (Haiku): Fast, read-only codebase exploration
• Plan (Inherits): Research for plan mode
• general-purpose (Inherits): Complex multi-step tasks
• Bash (Inherits): Command execution in separate context
• claude-code-guide (Haiku): Questions about Claude Code features

Agent Teams

When work exceeds a single subagent's context window, needs sustained parallelism, or requires cross-session coordination — use agent teams instead of standalone subagents.

Teams vs standalone subagents:

• Standalone subagent — self-contained task, returns summary to caller, caller's context absorbs output
• Agent team — multiple teammates with shared task list, coordinate via SendMessage summaries, each teammate has its own context window

Core mechanics:

1. TeamCreate — creates a named team
2. TaskCreate — adds tasks to the team's shared task list (with optional blockedBy dependencies)
3. Spawn agents with team_name parameter — they join as teammates, claim tasks, coordinate via SendMessage
4. Teammates go idle when no unclaimed tasks remain; TeammateIdle hooks can inject follow-up work

Design rules:

• Never use standalone subagents for user-requested parallel work. Standalone subagents inject full output into the caller's context via TaskOutput. Teammates communicate via short SendMessage summaries and share task lists.
• Tasks must be self-contained. Each task description must include enough context for any teammate to pick it up — teammates don't share conversation history.
• Use blockedBy for sequencing. When task B depends on task A's output, set the dependency explicitly rather than relying on execution order.
• Keep SendMessage summaries concise. Teammates receive messages as injected context — verbose messages degrade reasoning quality.

When to use teams:

• User explicitly requests parallel agents / teammates / workers
• Work decomposes into 3+ independent tasks that benefit from parallel execution
• Total work would exceed a single subagent's context budget
• Tasks need coordination checkpoints (one agent's output feeds another's input)

Architecture patterns, team coordination examples, and pipeline designs: see ${CLAUDE_SKILL_DIR}/references/patterns.md.

Evaluation Criteria

When evaluating a subagent, assess these five dimensions:

• Trigger Accuracy (25%) — Does Claude delegate at the right times? Test with: direct invocation, implicit matching, and non-matching tasks.
• Task Completion (30%) — Does the agent follow its workflow and produce the expected output? Test happy path, edge cases, and out-of-scope requests.
• Output Quality (25%) — Is output clear, complete, actionable, and format-compliant? Red flags: raw data dumps, missing information, inconsistent formatting.
• Context Efficiency (10%) — Does it return concise summaries? Does it avoid unnecessary tool calls and excessive file reads?
• Tool Usage (10%) — Does it use only granted tools efficiently? Does it handle tool errors gracefully?

Scoring: 4.5+ excellent, 3.5-4.4 good, 2.5-3.4 needs revision, <2.5 redesign. Full rubric with testing protocol: see ${CLAUDE_SKILL_DIR}/references/evaluation.md.

Common Issues and Fixes

Agent doesn't trigger

Description is too narrow or name has a typo. Broaden the description, add "use proactively", and verify the file loads with /agents.

Agent over-triggers

Description is too vague or overlaps with other agents. Narrow the scope, add explicit boundaries: "Security review for auth code only. NOT for general code review."

Wrong output format

No format specification in the prompt, or no example. Add an explicit ## Output Format section with a concrete example of the expected structure.

Incomplete task execution

Workflow isn't explicit enough. Add numbered steps with "IN ORDER", a completion checklist ("Before returning, verify:"), and explicit completion criteria.

Scope creep

Tools are too permissive or prompt doesn't set boundaries. Restrict the tools list and add a ## Constraints section with explicit prohibitions.

Poor context efficiency

No efficiency guidance. Add: "Use Grep to locate relevant code BEFORE reading entire files. Stop searching once you have sufficient information. Return a concise summary (max 500 words)."

Detailed diagnostic steps, error messages, and debug mode: see ${CLAUDE_SKILL_DIR}/references/troubleshooting.md.

Validation Checklist

Before deploying a subagent:

• name is lowercase with hyphens, no "anthropic" or "claude"
• description explains what AND when (under 1024 chars)
• description has no execution instructions
• tools is minimal (only what's needed)
• model matches task complexity
• System prompt starts with role definition
• System prompt has numbered workflow steps
• Output format is explicitly specified with example
• Constraints section prevents scope creep
• Completion criteria are defined
• Tested with representative tasks

Related Skills

• prompt-engineering — Load first for instruction design techniques (subagent prompts are system prompts)
• skill-engineering — Skills and subagents complement each other; skills run in main context, subagents run in isolation
• claude-code-sdk — Consult for API/configuration details