Fabler Labs → Guides → Claude Code Subagents

Claude Code subagents: how to write a custom subagent

Free · no signup · verified against the current docs · last updated July 2026

A subagent is a specialized assistant that runs in its own context window with its own system prompt, its own tool access, and (optionally) its own model. Claude Code delegates a matching task to it, the subagent works independently, and only the result comes back to your main conversation. This guide covers what they're actually for, the exact file format, a complete copy-paste example, and the mistakes that make people give up on them.

Why subagents exist (it's not really about speed)

The headline benefit people expect is parallelism. The real, everyday win is context protection. A search that would dump 4,000 lines of file contents into your main window instead happens inside the subagent and returns a five-line answer. Your main conversation stays focused on the decision, not the raw material behind it. The other reasons to reach for one:

• Enforce constraints — a review subagent can be read-only, so it physically cannot edit files.
• Reuse a configuration — encode "how we review code here" once, use it in every project.
• Control cost — route mechanical sweeps to a cheaper, faster model like Haiku and keep your best model for the hard call.

Rule of thumb: reach for a subagent when a side task would flood your main context with output you won't reference again — or when you keep spawning the same kind of worker with the same instructions. That repetition is the signal to make it a file.

Where the files live

A subagent is just a Markdown file with YAML frontmatter. Where you put it decides who can use it:

• .claude/agents/ in your repo → a project subagent. Check it into version control so your team shares and improves it. Ideal for anything codebase-specific.
• ~/.claude/agents/ → a personal subagent available in every project on your machine.

When two subagents share a name, the higher-priority location wins (managed > project > personal). One gotcha worth knowing: if the agents directory didn't exist when your session started, Claude Code won't detect a newly created one until you restart.

The frontmatter fields

Four fields cover almost every subagent you'll write:

• name — the identifier you (or Claude) use to invoke it.
• description — the most important field. Claude reads this to decide when to delegate automatically. Write it like a job posting: what the subagent is for and when to use it. Vague description → it never gets called.
• tools — the tools it may use. Omit it to inherit all tools, or list a subset to lock it down (e.g. Read, Grep, Glob for a read-only reviewer).
• model — sonnet, opus, haiku, fable, a full model ID, or inherit. Defaults to inherit (uses your main conversation's model).

There are more advanced fields — disallowedTools, permissionMode, maxTurns, skills, isolation (run in a throwaway git worktree) — but you rarely need them on day one. Start with the four above.

A complete, working example

Here's a read-only code-reviewer you can drop into .claude/agents/code-reviewer.md today. Note the tight description (so it's auto-invoked after edits), the restricted tools (it can read and run commands but not write), and a model choice:

---
name: code-reviewer
description: Expert code reviewer. Use proactively after writing or
  changing code, before committing. Focuses on correctness bugs,
  security issues, and clear simplifications.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Review ONLY the current diff, not the
whole repo. Run `git diff` (and the test command if one exists) to see
what actually changed and how it behaves.

For each finding, output:
- **Severity**: bug | risk | nit
- **Location**: file:line
- **What's wrong**: one sentence, concrete.
- **Failure case**: the input or state that triggers it.
- **Fix**: the smallest change that resolves it.

Rules:
- Prioritize correctness and security over style. Lead with the worst issue.
- Do not invent problems to look thorough. If the diff is clean, say so.
- Never edit files — you are read-only. Report; the human decides.
- Skip findings you cannot tie to a concrete failure or a real cleanup.

To use it, just ask: "Use the code-reviewer agent to review my changes." Because the description says "use proactively after changing code," Claude will also reach for it on its own at the right moment.

What makes a subagent good (and what kills it)

1. The description is the whole game. It's how Claude decides to delegate. "Reviews code" is too vague; "Use proactively after changing code, before committing" tells it exactly when.
2. Give it a feedback loop, not just instructions. A reviewer that runs git diff and the tests sees reality; one that only reasons about text hallucinates issues. Tell it to observe, not just opine.
3. Constrain the tools on purpose. A read-only reviewer that can't write is safer and more focused. Least privilege is a feature.
4. One job per subagent. A "reviewer + refactorer + doc-writer" does all three badly. Split them; they're cheap.
5. Match the model to the work. Mechanical sweeps → Haiku. Hard reasoning → your top model. Don't pay Opus prices to grep.