Skip to content

C2 · lesson 6 · 8 min read

Subagents

Delegate focused work to specialised agents that have their own context window, tools and permissions.

Ընտրեք տեքստը՝ հայերեն թարգմանությունը տեսնելու համար։Highlight text to see Armenian. Machine-assisted translation; English is the source of truth.

A subagent is a specialised assistant that Claude Code can hand a task to. It has its own context window, its own system prompt, and its own tools and permissions. It does the work and sends back only a summary. That keeps the main conversation focused and lets you give a narrow job narrow powers.

main sessiontf-reviewer (read-only)Explore (built-in)task →← summary
The main session delegates and gets a summary back; the subagent's reading stays in its own context.

Where they come from

Source Scope
Managed settings Organisation (highest priority)
--agents '<json>' on the CLI This run
.claude/agents/*.md This project
~/.claude/agents/*.md You, every project
A plugin’s agents/ The plugin (lowest)

When two sources define the same name, the one higher in this table wins.

There are also built-in subagents. Explore searches the codebase read-only, Plan researches during plan mode, and general-purpose has all tools.

Defining one

---
name: tf-reviewer
description: Reviews Terraform changes for security and cost risks. Use proactively after any .tf file changes.
tools: Read, Grep, Glob, Bash(terraform plan *)
model: sonnet
---

You review Terraform. For each finding give file:line, severity, and a fix.
Flag: public S3 buckets, 0.0.0.0/0 ingress, IAM "*" actions, missing encryption,
and resources that would be destroyed. Never propose applying anything.

Only name and description are required. Other useful fields include tools and disallowedTools, model, permissionMode, maxTurns, skills, mcpServers and isolation: worktree.

How delegation happens

Claude decides to delegate based on the description, so write it the way you’d write a tool description: what the subagent does and when to use it. Words like “use proactively” encourage automatic delegation. You can also ask for it directly: “have tf-reviewer check this”.

Recap

  • Subagents get their own context, prompt, tools and permissions, and return a summary.
  • They’re defined as Markdown with frontmatter in .claude/agents/ or ~/.claude/agents/. Only name and description are required.
  • The description drives delegation. Give a narrow job a narrow toolset.
  • Explore, Plan and general-purpose are built in.

$ ./try-it.sh

Try it: a read-only Terraform reviewer

  1. Create .claude/agents/tf-reviewer.md from the example in this lesson, with tools limited to Read, Grep, Glob and Bash(terraform plan *).
  2. Ask Claude to review the networking module and check that it delegates to tf-reviewer.
  3. Ask the reviewer to edit a file and confirm that it can't, because Edit isn't in its tool list.
  4. Compare how much of the main conversation the review used with doing the same review inline.

Check yourself

3 questions. Original practice questions, not taken from the real exam.

  1. A long session is running out of context because Claude keeps reading dozens of Terraform files to answer review questions.

    1. What's the main benefit of moving the review to a subagent?

  2. You create .claude/agents/tf-reviewer.md with only a body, no frontmatter, and Claude never uses it.

    2. Which fields are required for a subagent definition?

  3. You want a security reviewer subagent that can inspect code and run terraform plan but can't change files, and that Claude picks automatically after Terraform edits.

    3. Which two choices achieve that? (Choose two.)

    Choose 2.

Answer every question to check.