Subagent Design skill for Claude Code

A subagent earns its file when it does one of two things: absorbs noisy work (searches, logs, test output, large files) so the main context gets only a short result, or enforces a role with a restricted toolset. A good one is picked at the right moment from its description, needs no conversation history to do its job, and returns output the parent can act on without re-reading anything.

Subagent or something else?

Need	Use
Isolate exploration or verbose output from the main thread	Subagent
A role with fewer tools (read-only reviewer, no-network researcher)	Subagent
Run independent investigations in parallel	Several subagent calls in one turn
A procedure the main thread should follow with full context	Skill
A skill that should run isolated	Skill with context: fork
Always-on project facts	CLAUDE.md
Fully separate parallel sessions editing code	Git worktrees (git-worktree-parallelism)

Check the built-ins first: general-purpose, Explore (fast, read-only codebase search), and Plan. Do not create a custom agent that duplicates them.

File format

Project agents go in .claude/agents/<name>.md (commit them); personal ones in ~/.claude/agents/<name>.md; plugins ship them in agents/. On a name clash the project agent wins over the user agent. /agents lists, creates, and edits them interactively.

---
name: code-reviewer
description: Reviews a diff for correctness, security, and missed edge cases and returns ranked findings with file:line references. Use proactively after any non-trivial code change and before committing.
tools: Read, Grep, Glob, Bash
model: sonnet
skills: owasp-review
---

You are a senior reviewer. You receive no conversation history: everything you need is
in the task message and the repository.

## Procedure
1. Run `git diff --stat` and `git diff` (or the range given in the task).
2. Read each changed file fully around every hunk; follow calls one level out.
3. Check: logic errors, unhandled errors, input validation, authz, concurrency,
   resource leaks, missing tests for changed behavior.

## Constraints
- Read-only. Never edit files, never commit, never push.
- Report only issues you can point to in the code. No style nits a linter would catch.

## Output (exactly this shape, max 40 lines)
VERDICT: approve | changes-requested
FINDINGS:
- [high|medium|low] path/file.ts:42 - problem - concrete fix
TESTS-MISSING:
- behavior that changed without a test

Fields: name (lowercase-hyphen), description, tools (comma-separated; omit to inherit every tool including MCP tools), model (sonnet, opus, haiku, or inherit), skills (skills whose full content is preloaded into the agent’s context).

Workflow

- [ ] 1. Name the job and the noise it absorbs, in one sentence
- [ ] 2. Choose tools (minimum set) and model
- [ ] 3. Write the description for delegation
- [ ] 4. Write the prompt: role, inputs, procedure, constraints, output contract
- [ ] 5. Test explicit invocation, then automatic delegation
- [ ] 6. Tune from transcripts; commit with a CLAUDE.md line on when it is used

2. Tools and model

Role	Tools	Model
Codebase researcher / locator	Read, Grep, Glob	haiku or sonnet
Reviewer / auditor	Read, Grep, Glob, Bash (for git diff)	sonnet; opus for security-critical
Test runner / log triager	Bash, Read, Grep	haiku or sonnet
Implementer on a scoped task	Read, Edit, Write, Bash, Grep, Glob	inherit
Planner / architect	Read, Grep, Glob	opus or inherit
Web researcher	WebSearch, WebFetch, Read	sonnet

• Omitting tools grants everything, including destructive Bash and every MCP server. List tools explicitly for every agent except deliberate generalists.
• Bash is the escape hatch from any restriction. A “read-only” agent with Bash is read-only by instruction, not by enforcement; pair it with permission deny rules or a PreToolUse hook if that matters.
• Cheaper models suit high-volume, well-specified work. Use the strongest model where judgment is the product (review, planning).

3. Description for delegation

The main thread routes by description, like skills. Include:

• What it does and what it returns, with concrete nouns.
• When to use it, in the situations that actually occur (“after code changes”, “when a test fails”, “before answering questions about unfamiliar code”).
• “Use proactively” when it should be chosen without the user naming it.
• A boundary when roles overlap (“Not for fixing; reports only”).

Vague descriptions (“Helps with code quality”) are never delegated to automatically.

4. The prompt

The agent starts with no conversation history. Its system prompt plus the parent’s task message are all it knows. Structure:

1. Role and context limits - “You receive no history; rely on the task message.”
2. Inputs expected - what the parent must pass (paths, diff range, error text).
3. Procedure - numbered steps, including what to inspect first.
4. Constraints - forbidden actions, scope limits, time/turn budget.
5. Output contract - a fixed shape with a line cap. The final message is the only thing returned to the parent; everything else is discarded.
6. Stop conditions - when to return early (blocked, ambiguous, out of scope) and how to report that.

Output contract rules:

• Paths with line numbers, not prose descriptions of locations.
• Findings ranked by severity or relevance; cap the count.
• Distinguish verified facts from guesses (CONFIRMED: / UNVERIFIED:).
• Never return raw logs or whole files; quote at most the few lines that prove a point.

Delegation patterns

Pattern	Shape	Use when
Fan-out	2-5 researcher calls in one turn, each a distinct question	Independent questions over a large codebase
Context firewall	One agent reads 50 files, returns a 30-line map	Exploration would flood the main thread
Pipeline	planner -> main thread implements -> reviewer	Changes where a second opinion is cheap insurance
Verifier	test-runner after each change, returns pass/fail + first failure	Long fix loops with noisy test output

Parallel agents must not edit the same files. Parallelize read-only work freely; for parallel edits, give disjoint file sets or use worktrees.

Preloading skills

skills: a, b injects those skills’ full bodies at agent start. Preload only what every run needs; each preloaded skill costs its full token weight on every invocation. If the agent needs a skill only sometimes, leave it discoverable instead.

Gotchas

• The parent’s task message is often too thin (“review the changes”). Instruct the parent, in CLAUDE.md or the agent description, to pass paths, ranges, and the goal.
• Subagents cannot spawn further subagents. Design flat hierarchies.
• Subagents do not ask the user clarifying questions mid-run. Give them a stop condition that returns the question to the parent instead.
• Every subagent call re-reads files the parent may already have read. Delegating tiny tasks costs more than doing them inline.
• An agent that returns 300 lines has defeated its own purpose. Enforce the cap.
• Editing an agent file mid-session: verify with /agents that the new version is loaded before judging behavior.

Verification

1. /agents lists the agent with the expected tools and model.
2. Explicit call: “Use the code-reviewer subagent on the last commit.” Check the result matches the output contract exactly and respects the line cap.
3. Automatic delegation: give 3 representative prompts without naming the agent and confirm it is chosen; give 2 near-miss prompts and confirm it is not.
4. Restriction check: ask it to do something outside its tools (edit a file) and confirm it refuses or reports it cannot.
5. Compare main-context size with and without delegation for a real task (/context). If the saving is small, the agent is not pulling its weight.

Output

**Agent:** .claude/agents/test-runner.md (project, committed)
**Job:** runs the affected test suites, returns pass/fail and the first failure with file:line
**Tools:** Bash, Read, Grep  **Model:** haiku  **Preloaded skills:** none
**Delegation:** chosen automatically in 3/3 test prompts, 0/2 near-misses
**Context saved:** typical failing run returns 18 lines instead of ~2,400 lines of test output
**CLAUDE.md:** added "Run tests through the test-runner subagent"