# How to Create Subagents or Nested Agent Patterns in Claude Skills

> Learn to create nested agent patterns and subagents in Claude Skills. Delegate complex tasks to independent agents while enforcing safety constraints.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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:

```python
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:

```javascript
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) (line 131), provides seven specialized subagents for SDLC tasks. Install and invoke pre-built subagents via CLI:

```bash

# Install the great_cto plugin containing 7 sub-agents

skills add great_cto

```

Then invoke specific subagents in your code:

```python
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) files within the skill directory structure, such as [`skill-creator/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/connect/SKILL.md), which declares available tools such as `web_fetch` or `rube_search_tools` that subagents inherit during execution.