Resist the urge to make a generic "helper agent". Subagents are valuable because they are narrow. Pick a single task you do at least three times a week with a clear input and output:

• code-reviewer — read a diff or file, report bugs and security issues
• ticket-formatter — turn a raw bug report into a clean GitHub issue
• research — multi-source web search, synthesize under 300 words
• commit-msg-writer — read git diff, draft a commit message in your conventions

Bad use case: "research anything". Too open. Use the dedicated research-agent pattern (Phase 5) for that.

For this recipe, build code-reviewer — it is the most widely useful starting point.

Subagents live in either of two locations (no local-scope option):

• User scope: ~/.claude/agents/<name>.md — applies in every session everywhere
• Project scope: .claude/agents/<name>.md inside a repo — applies only when Claude is launched from there

Project beats user when both define the same name. Name conflict precedence: Managed > CLI flag (--agent) > Project > User > Plugin.

mkdir -p ~/.claude/agents
touch ~/.claude/agents/code-reviewer.md

---
name: code-reviewer
description: "Use when the user asks for a second-opinion review on a diff or a file. Reports bugs, security issues, code-quality findings ranked by confidence. Independent — has not seen the parent's reasoning. Trigger phrases: 'review this code', 'second opinion on the diff', 'spot bugs in src/auth.ts'."
tools: ["Read", "Grep", "Glob", "Bash"]
---

You are a senior reviewer. Find real issues, not stylistic nitpicks.

Output exactly three sections:

## Critical (will break in production)
- One bullet per issue, with file:line and a one-sentence fix.

## Important (will hurt within a month)
- Same format. Things like missing error handling, race conditions, N+1 queries.

## Nits (only if asked)
- Skip these unless the parent explicitly asks for style feedback.

If the diff is clean, say so in one line. Do not invent issues to fill space.

Confidence threshold: only report findings you are at least 70% sure about. Below that, omit.

Key fields:

• description is what Claude Code reads to decide when to spawn the subagent. Be specific. Bad: "reviews code". Good: explicit trigger phrases the user actually says.
• tools restricts what the subagent can do. Read, Grep, Glob, Bash is enough for review. No Edit, Write — reviewers do not fix.

Other fields available in the frontmatter (most you will not need at the start): model, effort, maxTurns, disallowedTools, skills, memory, background, isolation. The only valid value for isolation is "worktree" — it spawns the subagent in a separate git worktree for clean isolation.

Run aiguide_validate_step. The validator checks that one of <cwd>/agents/, <cwd>/.claude/agents/, or ~/.claude/agents/ exists with at least one .md file inside.

In any Claude Code session:

Use the code-reviewer subagent on the last commit. I want a second opinion before I push.

Claude detects the description matches and spawns the subagent. The child reads the diff, runs whatever greps it needs, returns three sections. Your main window only sees the summary.

If Claude does not pick the agent up automatically, name it explicitly: "Use the code-reviewer subagent on src/auth.ts." Then go tighten the description so auto-detection works next time.

/agents lists every active subagent in the current session.

Two anti-patterns to avoid as you add more

• The "do everything" agent. If your description is more than two sentences, split it. Two narrow agents beat one wide one because Claude can route to them with confidence.
• Spawn-everywhere reflex. If the task is 30 seconds inline, do it inline. Spawn when the task is independent (review, research, parallel batch) or context-heavy (would flood the parent window).

Three to five focused subagents covers what a one-person team needs. Add more when you have a real recurring task you keep prompting from scratch.

When a subagent beats a skill

Skills are reusable instruction blocks injected by trigger words. Subagents are full child sessions with their own tools and context. Pick a subagent over a skill when:

• The work is heavy enough to flood your main context (search, review across many files)
• You want true isolation (a "fresh pair of eyes" without prior reasoning)
• You need a different tool scope (subagent gets only Read+Grep, your main gets everything)

Pick a skill when the task is short and the trigger is clear ("debrief this session", "use German voice"). Skills do not isolate — they extend your main session.