Claude Code Subagents

What this covers

Building a Claude Code subagent — an isolated worker with its own context window, system prompt, tool permissions, and model, which the main session delegates a self-contained task to and gets a summary back from. The focus is the decisions that make a subagent reliable: tool scope, model tier, and the trigger description. For writing the agent’s persona (the system-prompt body), see System Prompts & AI Personas.

When to use it

• Creating a specialized worker (code reviewer, test runner, researcher, doc writer) you’ll reuse
• Turning a role or persona into something the main session can delegate to
• Wanting a repeatable, team-standard agent instead of a one-off — for a quick generic agent, the built-in /agents command is simpler
• Locking a specific model and a minimal tool set so every invocation behaves predictably

Check for a built-in fit first

Claude Code ships with built-in subagents (Explore, Plan, general-purpose) and an interactive /agents creator. If the need is generic, use those. Build a custom agent when you want project-specific conventions, a locked model, a deliberate tool policy, or a naming/validation standard the whole team shares.

Define the role

Write the system-prompt body: who the agent is, what it does when invoked, and what it returns. Keep it focused on one job — a subagent is good at a self-contained task whose output can be summarized. (See System Prompts & AI Personas for authoring this well.)

Choose tools — least privilege

Restricting tools is a core benefit of subagents. Grant only what the task needs:

• Read-only worker (reviewer, explorer): Read, Grep, Glob
• Needs to run commands: add Bash
• Needs to modify files: add Edit / Write

Don’t over-grant. A reviewer that can only read is safer and more predictable than one that can also write.

Choose a model tier

Match cost to the task and lock it in the frontmatter so every invocation is predictable:

• Haiku — light or read-heavy work
• Sonnet — standard tasks
• Opus — complex reasoning

Write a strong description

This is the most important field — it’s what makes the main session actually delegate to the agent. Be specific about when to use it and on what kind of task. Vague descriptions get the agent ignored; overly broad ones make it fire on unrelated work.

Pick scope and path

• Project: .claude/agents/<name>.md — committed to the repo, shared with the team.
• User: ~/.claude/agents/<name>.md — available across all your projects.

Assemble the file

---
name: <kebab-case-name>
description: <what it does + the specific WHEN-to-use trigger>
tools: Read, Grep, Glob
model: sonnet
---

You are <role>. When invoked, <what to do>.
Return <what the summary should contain>.

Validate before relying on it

Confirm the frontmatter parses, name is unique and kebab-case, tools is the minimal set, model is set, and description is specific enough to trigger correctly. Then test the agent on a real task before depending on it — subagents run in isolated context and return only their final result, so a weak description or missing tool won’t surface until you actually invoke it.