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.

55 min · Reviewed 2026

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

# .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.One markdown file, one scoped agent. Frontmatter controls tools and MCP access.

Orchestrator patterns

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

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.A task that would take 5 minutes of serial reading done in 30 seconds of parallel subagents.

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.
— A Claude Code power user

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 check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-agentic-shell-workflows-creators

What is the main idea of "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. parallel execution
2. sub-agents
3. delegation
4. agent orchestration
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. Tasks that split cleanly into parallel parts (explore 5 files independently)
4. Treat the AI output as automatically correct
What should a careful learner remember about "The 10-agent ceiling"?
1. Use AI to draft or organize ideas about sub-agents, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about sub-agents be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about sub-agents.
Which action would help you apply "Agentic Shell Workflows — Claude Code Sub-Agents in Practice" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Jobs with different tool needs (one agent reads DB, another edits code)

← Back to interactive lesson

Tendril · Creators · AI-Assisted Coding

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.

55 min · Reviewed 2026

A Small Team in Your Terminal

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

# .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.One markdown file, one scoped agent. Frontmatter controls tools and MCP access.

Orchestrator patterns

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

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.A task that would take 5 minutes of serial reading done in 30 seconds of parallel subagents.

Scoped tools as safety

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.
— A Claude Code power user

End-of-lesson check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-agentic-shell-workflows-creators

What is the main idea of "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. Sub-agents turn Claude Code from a coding assistant into a small engineering team that works in parallel.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Agentic Shell Workflows — Claude Code Sub-Agents in Practice"?
1. parallel execution
2. sub-agents
3. delegation
4. agent orchestration
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. Tasks that split cleanly into parallel parts (explore 5 files independently)
4. Treat the AI output as automatically correct
What should a careful learner remember about "The 10-agent ceiling"?
1. Use AI to draft or organize ideas about sub-agents, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about sub-agents be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about sub-agents.
Which action would help you apply "Agentic Shell Workflows — Claude Code Sub-Agents in Practice" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. Jobs with different tool needs (one agent reads DB, another edits code)

← Back to interactive lesson