How to Create Subagents or Nested Agent Patterns in Claude Skills

Claude Skills support nested agent patterns by spawning subagents that run independent reasoning loops with isolated context budgets, allowing parent agents to delegate complex tasks while enforcing read-only safety constraints.

Claude Skills are packaged instruction sets that define how AI agents perform tasks within the Claude ecosystem. When a complex problem requires decomposition into smaller, independent operations, you can create subagents or nested agent patterns in Claude Skills to handle specialized sub-tasks. According to the ComposioHQ/awesome-claude-skills repository, these nested patterns follow strict architectural guidelines for isolation and safety as defined in mcp-builder/reference/evaluation.md.

Architecture of Subagents in Claude Skills

The nested agent pattern follows a five-step delegation flow that maintains separation of concerns between parent and child agents.

Delegation Flow

A parent skill initiates the process by declaring a high-level goal and determining that delegation is necessary. It spawns a subagent by issuing a run command to the Claude SDK or by invoking the agent.run tool. The subagent receives a focused prompt describing the specific sub-task, executes its own tool calls (such as reading documentation or fetching web data), and returns a concise answer to the parent for integration into the overall workflow.

Context Isolation

Each subagent operates with its own context budget, preventing the parent agent from exhausting its token window. This isolation ensures that complex multi-step operations in subagents do not degrade the performance of the parent orchestration layer. The evaluation guidelines in mcp-builder/reference/evaluation.md (lines 182-208) mandate that subagents maintain separate reasoning loops and tool execution contexts.

Safety Constraints and Isolation

Subagents in the Claude Skills framework operate under strict safety guidelines to prevent unintended state mutations.

Read-Only Operations

According to mcp-builder/reference/evaluation.md (lines 207-208), subagents must perform only read-only or idempotent operations unless explicitly granted write permissions. This constraint ensures that exploratory subagents cannot destructively modify systems while researching or testing hypotheses. The parent agent maintains control over state-changing operations.

Parallel Execution

The architecture supports running multiple subagents in parallel, allowing different branches of a problem to be explored simultaneously. As documented in mcp-builder/reference/evaluation.md (line 207), parallel subagents can crawl different documentation sources or test separate API endpoints concurrently, with the parent aggregating results into a unified response.

Implementing Parent-Child Agent Patterns

You can implement subagent patterns using the Claude Agent SDK in Python or JavaScript, or by leveraging pre-built skill packages.

Python SDK Implementation

Use the claude_agent_sdk to instantiate a parent agent and spawn subagents via the run_subagent method:

from claude_agent_sdk import ClaudeAgent, ClaudeAgentOptions

# Initialize parent skill context

parent = ClaudeAgent(
    options=ClaudeAgentOptions(
        name="parent-skill",
        description="Orchestrates sub‑agents to research APIs"
    )
)

# Define focused sub-task prompt

sub_prompt = """
You are a research sub‑agent. Find the latest version of the OpenAI Python SDK
and list its major new features. Return only the version string and a bullet list
of features.
"""

# Execute subagent with restricted tools

sub_result = parent.run_subagent(
    prompt=sub_prompt,
    max_tokens=500,
    tools=["web_fetch"]  # Read-only web access only

)

print("Sub‑agent answer:", sub_result)

JavaScript SDK Implementation

For Node.js environments, use runSubagent with Promise.all to execute parallel subagents:

import { ClaudeAgent, ClaudeAgentOptions } from "claude-agent-sdk";

const parent = new ClaudeAgent({
  options: new ClaudeAgentOptions({
    name: "parent-skill",
    description: "Runs parallel sub‑agents for API comparison"
  })
});

const prompts = [
  "Compare the authentication flows of GitHub and GitLab APIs.",
  "List rate‑limit headers for Twitter and Mastodon APIs."
];

// Launch concurrent subagents
const subResults = await Promise.all(
  prompts.map(p => parent.runSubagent({ prompt: p, tools: ["web_fetch"] }))
);

subResults.forEach((r, i) => console.log(`Result ${i+1}:`, r));

Using Pre-Built Agent Packages

The repository includes ready-made subagent collections. The great_cto skill, documented in README.md (line 131), provides seven specialized subagents for SDLC tasks. Install and invoke pre-built subagents via CLI:

# Install the great_cto plugin containing 7 sub-agents

skills add great_cto

Then invoke specific subagents in your code:

from claude_agent_sdk import ClaudeAgent

parent = ClaudeAgent(name="sdlc-orchestrator")
answer = parent.run_subagent(
    prompt="You are the QA‑engineer sub‑agent. Generate a test plan for a new REST endpoint.",
    tools=["rube_search_tools"]
)
print(answer)

Real-World Use Cases

Nested agent patterns solve specific architectural challenges in production Claude Skills implementations.

Large-Scale SDLC Pipelines

The great_cto plugin orchestrates seven specialized subagents—including tech-lead, senior-dev, and qa-engineer roles—to cover architecture, testing, security, and deployment phases. As referenced in README.md (line 131), this pattern allows each subagent to focus on its domain expertise while the parent coordinates the overall development lifecycle.

Incremental Development with Checkpoints

The subagent-driven-development skill, mentioned in README.md (line 148), dispatches independent subagents for each development iteration. The parent inserts code-review checkpoints between iterations, ensuring quality gates before subsequent subagents modify the codebase.

Summary

• Subagents run isolated reasoning loops with separate context budgets to prevent token exhaustion in parent agents.
• Safety constraints defined in mcp-builder/reference/evaluation.md require subagents to perform read-only, non-destructive operations unless explicitly authorized.
• Parallel execution allows multiple subagents to operate simultaneously on different problem branches.
• Implementation uses run_subagent (Python) or runSubagent (JavaScript) methods from the Claude Agent SDK, with optional pre-built packages like great_cto available via the skills add command.

Frequently Asked Questions

Can subagents perform write operations or modify state?

No. According to mcp-builder/reference/evaluation.md (lines 207-208), subagents must perform only read-only or idempotent operations. They cannot mutate state unless the parent skill explicitly grants write permissions through specific tool configurations.

How many subagents can run simultaneously?

The architecture supports running multiple subagents in parallel. As documented in mcp-builder/reference/evaluation.md (line 207), you can spawn concurrent subagents to explore different branches of a problem simultaneously, limited only by your API rate limits and compute resources.

Do subagents share the parent's token context window?

No. Each subagent maintains its own context budget and isolated reasoning loop. This isolation prevents subagent operations from consuming the parent agent's token allocation, ensuring the orchestration layer remains responsive even during complex sub-tasks.

Where are subagent behaviors and prompts defined?

Subagent behaviors are defined in SKILL.md files within the skill directory structure, such as skill-creator/SKILL.md for custom agents or pre-built packages like great_cto. Tool access for subagents is configured in files like connect/SKILL.md, which declares available tools such as web_fetch or rube_search_tools that subagents inherit during execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}