Subagent Engineering

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

Skill(ai-helpers:prompt-engineering)

Skip only for trivial edits (typos, formatting).

Route to Reference

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.

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

permissionMode

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 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

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 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 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