Subagent Execution

When a skill needs to perform a complex subtask — searching a large codebase, running a multi-step pipeline, or processing files in parallel — it can delegate that work to a subagent. A subagent is a separate agent instance that gets its own context window, its own tool access, and its own conversation history. When the subagent finishes, it returns a summary to the parent, keeping the parent's context clean and focused.

The Fork Execution Model

Agents like Claude Code, Cursor, and Windsurf support two execution modes for skills: inline and fork. The default is inline, where the skill's instructions execute directly within the current conversation context. Fork mode, specified with context: fork in the frontmatter, launches a subagent in an isolated context window.

Think of it like the Unix fork() system call. The child process (subagent) inherits a snapshot of relevant context from the parent, but operates independently. Anything the subagent reads, writes, or reasons about does not consume tokens in the parent's context window. When the subagent completes, only its final output — a concise summary — is injected back into the parent conversation.

---
description: Analyze all test files and report coverage gaps
context: fork
allowed-tools:
  - Read
  - Glob
  - Grep
---

# Test Coverage Analyzer

You are a test coverage analysis agent. Your job is to:

1. Use Glob to find all source files matching `src/**/*.ts`
2. Use Glob to find all test files matching `src/**/*.test.ts`
3. Compare the two lists to identify source files without corresponding tests
4. For each untested file, Read it and identify the key exported functions
5. Return a structured report of coverage gaps

## Output Format

Return a markdown table with columns:
| File | Exported Functions | Test Status | Priority |

Focus on files with complex logic. Utility files with simple exports are low priority.

This skill uses context: fork because it may need to read dozens of files to build its analysis. Without forking, every file read would consume tokens in the parent conversation, potentially exhausting the context window. With forking, the subagent does all the heavy lifting in isolation, and the parent only receives the final coverage report.

Inline vs Fork: How They Differ

The difference between inline and fork execution affects several aspects of how a skill runs:

• Context isolation. Inline skills share the parent's context window. Every tool call, every file read, every reasoning step happens in the same context. Fork skills get a fresh context window, so their intermediate work is invisible to the parent.
• Token efficiency. An inline skill that reads 20 files adds all 20 files to the parent context. A forked skill reads those same 20 files in its own context and returns only the distilled result.
• Execution speed. Forked skills have startup overhead because a new agent must be initialized. For quick tasks (under 5 tool calls), inline is usually faster. For heavyweight tasks, the context savings of fork more than compensate.
• State visibility. Inline skills can see and react to the full conversation history. Forked skills only see what was passed to them at launch time. They cannot reference earlier messages in the parent conversation.

The Task Tool for Subagent Dispatch

Skills can also programmatically launch subagents using the Task tool. The Task tool is available as a built-in tool in the agent and allows a skill to spin up one or more subagents dynamically, even if the skill itself is running inline. This is the mechanism behind parallel work distribution.

---
description: Refactor a module by analyzing, planning, and executing in parallel
allowed-tools:
  - Task
  - Read
  - Write
---

# Parallel Refactor

When the user provides a module path, launch three subagents in parallel:

## Step 1: Parallel Analysis

Use the Task tool to launch these three agents simultaneously:

**Agent 1 — Dependency Analyzer:**
"Analyze all imports and exports in the module at $ARGUMENTS.
 Identify circular dependencies, unused imports, and tight coupling.
 Return a dependency report."

**Agent 2 — Pattern Detector:**
"Read all files in $ARGUMENTS and identify code smells:
 duplicated logic, overly long functions (>50 lines),
 deeply nested conditionals (>3 levels), and magic numbers.
 Return a list of issues with file paths and line numbers."

**Agent 3 — Test Impact Analyzer:**
"Find all test files that import from $ARGUMENTS.
 Determine which tests will need updates if the module's
 public API changes. Return a test impact report."

## Step 2: Synthesize

After all three agents return, combine their reports into a
unified refactoring plan. Prioritize changes that address
multiple issues simultaneously.

## Step 3: Execute

Apply the refactoring plan, starting with the highest-impact
changes. Run tests after each change to ensure nothing breaks.

In this example, the parent skill orchestrates three subagents that each tackle a different aspect of the analysis. Because they run in parallel through the Task tool, the total wall-clock time is roughly equal to the slowest agent rather than the sum of all three.

What Subagents Inherit

When a subagent is forked, it receives a curated subset of the parent's state:

• The task prompt. The description of what the subagent should do, as specified in the Task tool call or the skill body.
• Tool access. The subagent has access to the tools specified in its configuration. By default, subagents get the same tool access as the parent, but this can be scoped down.
• Working directory. The subagent operates in the same filesystem as the parent, so it can read and write the same files.

What subagents do not inherit:

• Conversation history. The subagent does not see prior messages between the user and the agent. It starts fresh with only its task prompt.
• Parent context contents. Files the parent has already read are not pre-loaded into the subagent's context. The subagent must read them again if needed.

Result Handling

When a subagent completes its work, it produces a result that flows back to the parent. The parent sees this as the return value of the Task tool call. The result is typically a text summary — the subagent's final message — which is much smaller than the full context the subagent consumed during its work.

Practical Patterns

Here are the most common patterns for subagent usage in skills:

1. Fan-out / fan-in. Launch N subagents in parallel, each handling a slice of the work. Collect results and synthesize. Great for codebase-wide analysis.
2. Pipeline. Chain subagents sequentially where each agent's output becomes the next agent's input. Good for multi-phase workflows like analyze → plan → execute.
3. Scout agent. A lightweight forked agent that explores the codebase and returns findings, so the parent can make decisions without consuming context on exploration.
4. Specialist delegation. Route different types of work to agents with different tool configurations. A "read-only analyst" agent gets only Read and Grep. A "builder" agent gets Write and Bash.

What's Next

Now that you understand how subagent execution works, the next lesson explores the different agent types available — specialized subagent configurations optimized for specific categories of work.