Lesson 41 of 2116
Agentic Shell Workflows — Claude Code Sub-Agents in Practice
Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel. Let's build a real sub-agent workflow end to end.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1A Small Team in Your Terminal
- 2sub-agents
- 3parallel execution
- 4delegation
Concept cluster
Terms to connect while reading
Section 1
A Small Team in Your Terminal
A sub-agent is a separately-scoped Claude instance spawned by your main session to handle a focused job. Up to 10 can run in parallel. Each has its own system prompt, tool access, and MCP servers. You stop being one person typing and become an orchestrator directing specialists.
When to reach for sub-agents
- Tasks that split cleanly into parallel parts (explore 5 files independently)
- Jobs with different tool needs (one agent reads DB, another edits code)
- Long-running investigations where main session would spiral
- Research tasks you can batch (summarize every file in src/)
- Multi-step pipelines (plan → implement → test → review)
Defining a sub-agent
One markdown file, one scoped agent. Frontmatter controls tools and MCP access.
# .claude/agents/explorer.md
---
name: explorer
description: Map unfamiliar code — summarize files, identify entry points, trace data flow
tools:
- Read
- Grep
- Glob
mcpServers:
# Explorer gets read-only GitHub access; no edit privileges.
github-readonly:
command: npx
args: ["-y", "@modelcontextprotocol/server-github", "--readonly"]
---
You are an exploration agent. Your job:
1. Read files requested by the parent agent.
2. Produce concise, structured summaries.
3. Cite file paths and line numbers for every claim.
4. Never edit files — explore only.Orchestrator patterns
Compare the options
| Pattern | Use case |
|---|---|
| Fan-out | Split a job across N agents, merge results (explore 10 directories) |
| Pipeline | Sequence of specialized agents (planner → coder → tester → reviewer) |
| Supervisor | Main agent supervises narrow workers (main plans, subagents execute) |
| Sandbox | Run risky commands in a scoped subagent with limited tools |
A real fan-out session
A task that would take 5 minutes of serial reading done in 30 seconds of parallel subagents.
You (in main Claude Code session):
"Use the explorer agent to summarize each of these 5 files in parallel:
src/auth/login.ts, src/auth/signup.ts, src/auth/reset.ts,
src/auth/sessions.ts, src/auth/middleware.ts
Then synthesize a single auth-system overview."
Claude (main):
Spawns 5 explorer subagents, one per file, in parallel.
Receives 5 summaries in ~30 seconds total.
Synthesizes a cross-file overview citing each summary.Scoped tools as safety
The best subagent designs restrict capabilities. An explorer that can only read. A tester that can only run tests. A deployer that can only run deploy scripts. Scoping prevents a single hallucinated command from wrecking your repo, and it makes audit trails trivial.
Debugging agent sessions
- Every subagent logs to .claude/logs/ — read these when things go sideways
- Use hooks on SubagentStart/Stop to track timing and token usage
- Ask the orchestrator to summarize what each subagent did at the end
- Keep agents single-responsibility — overloaded agents fail opaquely
A production-ready sub-agent registry
- explorer: read-only repo mapping
- tester: runs tests, reports failures, never edits
- reviewer: reviews diffs, read access only
- deployer: runs deploy scripts in a narrow shell
- researcher: web search and summarization, no code access
“You are no longer a typist. You are a conductor.”
Key terms in this lesson
The big idea: sub-agents transform Claude Code from assistant to orchestra. Define specialists, give each the minimum tools it needs, and compose them into workflows that are faster and safer than any single agent could be.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Agentic Shell Workflows — Claude Code Sub-Agents in Practice”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 50 min
AI-Assisted Code Review Workflows (for Teams)
Code review is the highest-leverage touchpoint in a team. Automating the noise with AI frees humans to focus on the irreducibly human parts. Let's design the workflow.
Creators · 50 min
Deploy Pipelines With AI in the Loop
AI belongs in CI/CD too. From PR previews to rollback judgment calls, agents can operate inside your pipeline safely — if you scope them right.
Creators · 75 min
Capstone: Ship a Real Full-Stack AI-Assisted Project
The creators capstone. You scope, design, build, test, deploy, and document a real full-stack project using an agentic workflow — end to end.