How to set up Claude Code subagents (with 4 copy-paste examples)

Published Oct 15, 2026 · 5 min read

Subagents are the most underused feature in Claude Code. A subagent is a specialist with its own system prompt, its own tool permissions and its own context window. Your main conversation stays clean while the specialist digs through files.

1. Where subagent files live

• .claude/agents/*.md: project subagents. Commit them so your team gets them.
• ~/.claude/agents/*.md: personal subagents, available in every project.

You can also create one interactively with the /agents command.

2. The file format

---
name: code-reviewer
description: Use proactively after code changes. Reviews the git diff for bugs and missing tests.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a strict but practical code reviewer. ...

• name: the identifier you and Claude refer to.
• description: the most important line. Claude reads it to decide when to delegate. Start with "Use proactively when…" to get automatic delegation.
• tools: an allowlist. Omit it to inherit all tools. A reviewer has no business holding Write.
• model: inherit, or an alias like sonnet, opus or haiku.

3. Four subagents worth having

1. planner (Read, Grep, Glob): produces a numbered plan, writes no code.
2. code-reviewer (read-only plus Bash for git diff): ends with APPROVE or CHANGES REQUESTED.
3. test-writer: writes tests, runs them, and never weakens an assertion to make one pass.
4. debugger: reproduce, hypothesize, verify, then fix the root cause.

4. Make Claude actually use them

Put the workflow in CLAUDE.md ("for multi-file changes, use the planner subagent first"), or chain them in a skill such as /ship-feature. You can also ask explicitly: "use the code-reviewer subagent on my diff."

5. Common mistakes

• A vague description, so Claude never delegates.
• Giving every subagent every tool.
• Writing a long essay as the system prompt. Keep it to a checklist of under 30 lines.

Want all four pre-built, plus skills, safety hooks and CLAUDE.md templates? Get the Claude Code Agent Starter Kit.

Source: the official subagents documentation at code.claude.com/docs/en/sub-agents.