Sub-Agents — Overview

A sub-agent is a markdown file at .claude/agents/<name>.md (project scope) or ~/.claude/agents/<name>.md (available across all projects). It defines a focused, specialised Claude instance that runs in its own context window with its own tool access and its own system prompt. The main Claude Code session delegates to it — automatically, based on the sub-agent’s description field, or explicitly when invoked by name.

The value isn’t that sub-agents are smarter. They aren’t. The value is that they keep the main session’s context clean. A research-style task that would otherwise pollute the main context with dozens of file reads runs inside the sub-agent and returns only the final answer. Long sessions stay sharp.

When to reach for one

Sub-agents earn their place when a task is repeatable, narrow, and noisy. The four sub-agents in this section all fit that pattern: a security scan before commit, a migration safety check, a structured re-orientation when reopening a stale project, an edge-case sweep on a new feature.

Don’t reach for a sub-agent when a single prompt to the main session would do. The cost is the file to maintain and the cognitive load of remembering it exists.

File shape

Every sub-agent has the same shape:

---
name: agent-name
description: When this agent should be invoked. The auto-delegation key — write it precisely.
tools: Read, Grep, Glob, Bash
model: sonnet
---

The system prompt. Direct, narrow, no fluff.
Define the input shape, the output shape, and the rules.

Four frontmatter fields matter:

name — kebab-case. Used in Use the <name> agent to... invocations.
description — Claude Code reads this to decide when to auto-delegate. Be specific about when. “Use after staging changes and before committing” is good. “Reviews code” is not.
tools — comma-separated list. Restrict to the minimum needed. A reviewer needs Read, Grep, Glob. A scanner needs Bash too. Most don’t need Write or Edit.
model — haiku, sonnet, or opus. Use Haiku for fast, narrow scans. Sonnet for everyday work. Opus for tasks that need genuine reasoning.

The body of the file is the system prompt. Write it the way you’d write any prompt: specific input expectations, structured output, named rules.

Installation

To install a sub-agent in a single project, drop the .md file into .claude/agents/ at the project root and commit it. Project sub-agents are version-controlled with the codebase and should be committed.

To install across every project, drop the file into ~/.claude/agents/ instead. User sub-agents aren’t tied to any repo.

The interactive /agents command also lets you create and edit sub-agents from inside Claude Code. Faster than hand-writing the markdown for first-time creation. Hand-writing is fine once the shape is familiar.

What follows

The next section covers the design principles for writing your own sub-agent. The four sections after that are complete sub-agent files ready to drop in. Pick the ones that match work you actually do — installing all four on principle is the wrong move.