Subagents

A subagent is a separate Claude that runs a side task in its own context window and returns only the answer.

Last updated: 29 Sep, 2026 · Claude Code

The video asks Claude Code itself what agents are and why to use them. The answer: specialised helpers it spawns with the Agent tool. Each runs in its own context window, does the work and returns a single summary, and sees only the prompt it is handed, not your conversation. Built-in ones are Explore, Plan, general-purpose, claude-code-guide, which answers questions about Claude Code, and statusline-setup.

The reasons it gives: context protection, since a search across hundreds of files comes back as a 200-word summary; parallelism, several running at once; specialisation, a focused tool set each; and an independent perspective, since a reviewing subagent does not see the reasoning that wrote the code. And when not to: when you already know the file path or the exact symbol, or the task is one line, spawning one costs more than doing it.

Each one also carries its own system prompt, tool list and permissions, which is what a subagent file sets.

The context window and compaction lesson said the context window is mostly file reads and command output. This is the tool that keeps it that way.

Asking Claude which subagents a project needs

Not sure what to create? The video asks: "based on this project, what subagents can I create?". Claude reads the repository and suggests ones that fit it: a notebook-lesson-reviewer that checks the teaching flow of the notebooks, and a langchain-api-verifier that checks the code against the current LangChain docs.

To create one, describe it and say where to save it, and Claude writes the file with a name, a description, a tools list, a model and a system prompt (subagents). The docs' own example is close to the subagent the video builds; here it is aimed at the project folder, with the video's extra instructions:

Create a project code-improver subagent in .claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code and
provide an improved version.

The code-improvement-advisor file and its memory

The file it produced, .claude/agents/code-improvement-advisor.md, as the video opens it. The description goes on for several lines of examples, cut here:

---
name: "code-improvement-advisor"
description: "Use this agent when the user asks for code improvement suggestions, refactoring advice, or quality reviews focused on readability, performance, and best practices. ..."
tools: Glob, Grep, Read, TaskStop, WebFetch, WebSearch
model: sonnet
memory: project
---

You are an elite Code Improvement Advisor ...

memory: project is the field to notice. It gives the subagent a folder of its own, .claude/agent-memory/code-improvement-advisor/, which the video's file explorer shows beside agents. The subagent reads its notes there at the start of each run and writes what it learns, so the next review starts from what the last one found. The scope decides where the folder lives (subagents):

The video runs the subagent with "review the code of the entire project and provide me suggestions". It works through the project in its own context and hands back findings grouped by high, medium and low severity. The session was still in plan mode, so nothing changed, and it offered to write the chosen fixes into plan.md.

The video starts that run from the wizard's library. Today you name the subagent in the prompt, or type @ and pick it, which makes sure that subagent runs:

@agent-code-improvement-advisor review the code of the entire project and provide me suggestions

This course's own subagent does one narrow job on the link shortener.

One subagent

---
name: bug-hunter
description: Search the codebase for silent data loss, where a write can overwrite existing data without warning. Use when auditing, not when fixing.
tools: Read, Grep, Glob
model: haiku
---

You look for one thing: a write that can destroy data that is already there.

For each risk, report the file, the function, and one sentence saying how it
happens. Do not suggest fixes and do not edit anything.

The same shape as a skill and a different job. description is how Claude decides to delegate to it, tools is what it may use, and cutting that list down is a real constraint rather than a hint. This one cannot edit anything, because Edit is not in its list.

model: haiku is the other reason to reach for one. Searching does not need your most expensive model, and routing that work to a cheap one is the difference between an audit you run weekly and one you run once.

Delegating to a subagent

> audit the project for silent data loss

Claude reads the description, hands the job to bug-hunter, and reports back what it found. Everything the subagent read on the way stays out of your conversation.

You can also call it directly: start the prompt with @agent-bug-hunter and that subagent runs even when its description would not have been picked. That is worth doing while you are still finding out whether the description is good enough.

What it costs

• It starts fresh. A subagent does not know your conversation unless it is a fork of it, so anything it needs has to be in the request or in the files.
• You get a summary, not the work. Good when the detail is noise, bad when you wanted to read it yourself.
• Descriptions live in your context. Every subagent's description is loaded at startup, so twenty verbose ones cost you before you type anything.

Related

• Previous: PreToolUse hook
• Next: Worktrees