Skip to content
BENIBIX Learn

Claude Code Subagent

AI⌨️ Claude CodeClaude Code Concepts

Also known as Custom subagent, .claude/agents, /agents

A helper agent you define in a Markdown file. Claude hands it tasks to do.

Think of it like

It is like a helper with one job card. You call them in, they do that job, and they report back.

Example

Emma makes a code-improver subagent. She gives it only Read, Grep and Glob. Claude now sends it code to review, and it can look but never edit.

Why it matters

Each subagent works in its own clean context. Big searches stay out of your main chat, and each helper gets only the tools it needs.

Definition

A Claude Code subagent is a helper you define in a Markdown file. The file sits in .claude/agents for one project, or in ~/.claude/agents for all of them. A short header gives it a name, says when to use it, and lists its tools and model. The text below the header is its own system prompt. Claude hands it a task, and it works in a fresh context and sends back a summary.

Example code

markdown
---
name: code-improver
description: Suggests code fixes. Use after writing code.
tools: Read, Grep, Glob
model: sonnet
---

You review code and suggest clear fixes.
A name, when to use it, its tools and model, then its own instructions.
A subagent is one file. Its header says who it is and what it may use.

Common mistake

Writing a vague description. Claude reads it to decide when to call the subagent, so a fuzzy one is never used.

Key takeaways

  1. 1
    One file each. Markdown with a header on top.
  2. 2
    Fresh context. It works apart and reports back.
  3. 3
    Only its tools. List just what the job needs.

Compare

Learn it properly