Claude Code Subagents for Parallel Data Work
What it is: Subagents are a built-in Claude Code feature, not a third-party package — separate, focused agents that Claude Code can delegate a piece of work to, each with its own context window, its own system prompt, and optionally a restricted set of tools. The main session decides when to hand off a task and reads back a summary instead of the subagent's full transcript.
Quick answer: Define a subagent as a Markdown file with YAML frontmatter (name, description, optional tool list) in .claude/agents/, or create one interactively with /agents. Use subagents to isolate noisy, exploratory work — like scanning a large dataset or trawling logs — so it doesn't bloat your main conversation's context.
Why it matters for data work
Data investigations tend to generate a lot of exploratory noise — profiling a table, grepping through logs, reading a dozen files to find the one that matters. Running that as a subagent keeps the exploration's raw output out of your main context; you get back a summary instead of every intermediate command, which keeps the primary session focused and leaves more room for the actual analysis.
Install & configure
Create a Markdown file under .claude/agents/ in your project (or ~/.claude/agents/ for a personal, cross-project agent). Required frontmatter is a name and a description Claude matches against when deciding whether to delegate; an optional tools list scopes which tools that subagent is allowed to use. The file body below the frontmatter is the subagent's own system prompt. The /agents command opens a library view of built-in, project, user, and plugin subagents (and any currently running) — on recent Claude Code versions it's for browsing and editing, not a creation wizard, so writing the file yourself (or asking Claude to scaffold one) is the normal way to create one.
Subagent or just a longer prompt?
Split work into a subagent when it's genuinely separable — a self-contained investigation whose detailed steps you don't need in your main transcript, and whose result you can summarize back in a few sentences. Keep it in the main session when the steps build on each other conversationally, or when you'll want to see and steer the intermediate work yourself. Spinning up a subagent for something trivial just adds overhead; it earns its keep on exploratory, context-heavy legwork.
Limits and gotchas
A subagent's context is isolated — it doesn't see your main conversation's history, so its instructions need to be self-contained, and anything it doesn't explicitly report back is lost when it finishes. That isolation also means you can't casually correct it mid-task the way you'd steer the main session; you mostly find out how it went after the fact. For data work specifically, be explicit in the subagent's prompt about what to summarize (row counts, specific findings, file paths) rather than assuming it knows what you'll want to see.
Troubleshooting
Most subagent problems come down to scoping — either the definition or the tool list.
- Claude never delegates to your subagent: tighten the
descriptionfield in the frontmatter — it's what Claude matches against when deciding whether a task fits. - Subagent's summary is missing what you needed: the subagent's own prompt didn't ask for it explicitly; make the expected output format part of its instructions.
- Subagent can't use a tool you expected it to have: check the tool list in its frontmatter — an omitted list usually inherits defaults, but an explicit restricted list will block anything not named.
- Project subagent doesn't show up: confirm the file is under
.claude/agents/at the project root Claude Code was launched from, not a subdirectory.
Author & links
Author: Anthropic
Docs: docs.claude.com/en/docs/claude-code/sub-agents
License: Proprietary — bundled with Claude Code
Related skills
Pair subagents with Claude Code hooks for deterministic automation around what a subagent's tool calls trigger, or package a repeated subagent invocation as a slash command.
← Back to Claude Code Skills