Claude Code - Sub-Agents - with Examples, Tools, Workflow Integration, and Session Strategies

Claude Code’s sub-agents are like specialized teammates you can summon inside your coding environment. Instead of asking your main assistant to do everything (debugging, reviewing, writing docs, analyzing data), you can spin up focused helpers with their own roles, permissions, and context.

This guide gives you the complete playbook:

• What sub-agents are

• When to use them (and when not to)

• How to create them (UI + files)

• Copy-paste examples

• The full tool list + cheat sheet

• How to incorporate them into your workflow while the main agent is running

• When to use inline orchestration vs separate sessions

---

What are sub-agents?

Sub-agents are scoped assistants with:

• Their own system prompt (role + rules)

• Their own tool permissions (what they’re allowed to do)

• Their own context window (fresh memory separate from your main thread)

You can either:

• Invoke them explicitly by name (use the code-reviewer subagent…)

• Or let Claude auto-delegate if your description matches their role

This separation keeps your main chat clean and makes tasks safer, faster, and more reliable.

---

When (and when not) to use sub-agents

✅ Great fits

• Multi-step tasks (e.g., research → write → review)

• Guardrails (a reviewer that enforces security standards)

• Specialized expertise (SQL queries, doc writing, profiling)

• Extensible workflows (swap in a TweetWriter without touching research logic)

❌ Overkill

• One-off questions

• Tiny edits or explanations that don’t need a dedicated context

---

How to create sub-agents

Option A — With the /agents UI

1. Run /agents in Claude Code

2. Click Create New Agent

3. Fill in:

   • Name

   • Description (when/why to use it — keep action-oriented)

   • Tools (leave blank to inherit all)

4. Save. Edit the system prompt if needed.

Option B — Markdown files

Sub-agents live in:

• Project scope → .claude/agents/

• User scope → ~/.claude/agents/

Example:

---
name: code-reviewer
description: Focused code review after each commit.
tools: Read, Grep, Glob, Bash
---

You are a senior reviewer. Always inspect diffs and enforce quality, security, and style.

---

Example sub-agents (drop into .claude/agents/)

(…examples for Code Reviewer, Debugger, Data Scientist, Reddit Researcher — unchanged here for brevity but included in full earlier…)

---

Full tool list

Sub-agents can be given these tools:

• Read → Read files

• Write → Create/edit files

• Grep → Search inside files

• Glob → Match file patterns (*.py, src/**)

• Bash → Run shell commands/tests

• MCP tools → External integrations (DBs, APIs, cloud services)

⚠️ If you omit the tools: line, the agent inherits all tools available in your main session.

---

Tool cheat sheet (by agent type)

---

Incorporating sub-agents into your workflow (while main agent is running)

(…section covering inline invocation, auto-delegation, chaining, /agents, Hooks, permissions, MCP, and workflow playbooks — as written in the prior draft…)

---

Using sub-agents in separate sessions

By default, sub-agents run inside your main session, returning results inline. But you can also spin up dedicated sessions where a sub-agent is the “main persona.”

Inline orchestration (default)

• Stay in one thread

• Call code-reviewer, debugger, etc. inline

• Results are merged into your main chat

• Great for continuity, orchestration, and quick workflows

Separate sessions

• Open a new Claude Code session and choose a sub-agent directly

• That session runs only with that agent’s prompt + tool permissions

• Benefits:

  • Focus: a long-lived debugging or research workspace without cluttering your main thread

  • Parallel work: keep multiple tabs open (e.g., data-scientist running queries while code-reviewer runs in another)

  • Isolation: huge contexts (like Reddit scraping notes) don’t pollute your main chat

Caveats

• Separate sessions don’t share state — you’ll need to copy/paste or sync context

• Each session enforces the agent’s tool list

• Edits to an agent file require restarting the session

Rule of thumb:

• Use inline for orchestration and everyday coding

• Use separate sessions for deep, focused, or long-lived specialist tasks

---

Best practices

• Small, focused agents > one giant multi-purpose agent

• Write prompts as checklists with constraints

• Restrict tools to enforce safety

• Version .claude/agents/ in your repo so the team shares agents

• Prefer explicit invocation for critical workflows

---

Quick starter pack

mkdir -p .claude/agents

Add these:

• code-reviewer.md

• debugger.md

• data-scientist.md

• reddit-researcher.md

Run /agents to verify.

---

Wrap-up

Sub-agents make Claude Code modular, safer, and smarter. They let your main agent stay conversational and orchestral, while specialists do the heavy lifting exactly when needed.

Start small: add a code-reviewer and a debugger. Once you feel the speedup, extend to data analysis, doc writing, or research — and explore running some inline, some as dedicated sessions.