# How to Use Context Fork to Run Claude Code Skills in Isolated Subagent Contexts

> Learn how to use context fork for Claude Code skills. Create isolated subagent contexts to prevent tool usage from polluting your main conversation memory. Optimize your Claude agent.

- Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- Tags: how-to-guide
- Published: 2026-03-12

---

**Setting `context: fork` in your Claude Code skill front-matter spins up a dedicated sub-agent with its own memory window, preventing tool usage from polluting the main conversation context.**

The `shanraisshan/claude-code-best-practice` repository documents how to leverage isolated subagent contexts to keep complex skill operations sandboxed. When you designate a skill with `context: fork`, Claude creates a separate execution environment where all tool calls occur independently from the primary agent.

## What Is Context Fork in Claude Code?

The `context: fork` directive is a front-matter configuration that changes how Claude Code executes a skill. Instead of running the skill body within the current conversation window, Claude spawns a **sub-agent**—a fresh instance with its own context window, model settings, and optional agent type.

According to the source analysis in [`reports/claude-agent-command-skill.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-command-skill.md), this isolation ensures that internal tool usage (such as `Read`, `Grep`, or `Bash` commands) cannot affect the caller's prompt history or variable state. The skill runs in a sandboxed environment, and only the final text output returns to the main conversation.

## How Context Fork Works Internally

The execution flow described in the repository follows a five-step process:

### 1. Front-Matter Parsing

Claude reads the skill's YAML front-matter at the start of execution. Detecting `context: fork` triggers the sub-agent launcher protocol rather than the standard inline execution.

### 2. Sub-Agent Creation

A new sub-agent instance initializes with the specified `agent:` type (defaulting to `general-purpose` if not provided). The context window starts completely empty, and optional `model:` settings apply only to this forked instance.

### 3. Isolated Execution

The skill's body transmits to the sub-agent. All subsequent tool calls—whether file reads, grep searches, or bash commands—execute **inside** that sub-agent's environment without touching the parent context.

### 4. Result Return

Upon completion, the sub-agent's final output (a text string) injects back into the original prompt as the skill's return value. The parent agent receives only the result, not the intermediate tool history.

### 5. Context Cleanup

The sub-agent's context discards automatically unless the skill explicitly persists data via hooks or external storage. This ensures no memory leaks between forked executions.

## Configuring the Subagent with Agent Types and Models

The [`best-practice/claude-skills.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-skills.md) file demonstrates that `context: fork` pairs with two optional front-matter keys:

- **`agent:`** – Specifies the sub-agent type. Options include `general-purpose` (default) or `fast-agent` for lighter-weight operations.
- **`model:`** – Overrides the model for the forked skill only, leaving the main conversation model unchanged.

Because the `agent` key only applies when `context: fork` is active (as noted in [`CLAUDE.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md)), you cannot use custom agent types for inline skills.

## Practical Code Examples

### Minimal Forked Skill for File Operations

The following example from the repository shows a basic skill that runs a `find` command in an isolated context:

```yaml
---
name: list-large-files
description: List files larger than 10 MiB in the current repo
argument-hint: [directory]
allowed-tools: Read, Grep, Bash
model: sonnet
context: fork          # ← run in its own sub-agent

agent: general-purpose # optional, defaults to general-purpose

---

# Skill body (Markdown or plain text)

Find all files under $0 larger than 10 MiB and return a bulleted list.

```bash
find $0 -type f -size +10M -print

```

```

When the user invokes `/list-large-files src/`, Claude spawns a sub-agent, executes the `find` command there, and returns the list without polluting the main prompt history.

### Forked Skill with Custom Agent Type

For lighter tasks requiring quicker turnaround, specify a `fast-agent`:

```yaml
---
name: security-scan
description: Run a static-analysis scan and summarize findings
argument-hint: [project-path]
allowed-tools: Bash, Read
model: opus
context: fork
agent: fast-agent   # lighter agent for quicker turnaround

---
Run the following scanner inside $0 and capture the output:

```bash
./scripts/scan.sh $0

```

Summarize the key security warnings in plain English.

```

The `fast-agent` handles the heavy analysis in a separate context, keeping the primary conversation responsive.

### Using Hooks with Forked Skills

The `Stop` hook executes within the sub-agent context, allowing Git operations to occur only after successful skill completion:

```yaml
---
name: generate-doc
description: Generate API docs and commit them
argument-hint: [source-dir]
allowed-tools: Bash, Edit, Git
model: sonnet
context: fork
hooks:
  Stop:
    - hooks:
        - type: command
          command: "git add docs/ && git commit -m 'Update generated docs'"
---

# Generate Markdown docs for $0

./scripts/gen-docs.sh $0 > docs/api.md

```

Because the hook runs inside the forked sub-agent, the commit occurs only if the documentation generation succeeds, and the Git state remains isolated from the main conversation until the final result returns.

## Summary

- **Context fork** creates isolated sub-agent environments for Claude Code skills, preventing tool usage from affecting the main conversation.
- Set `context: fork` in the YAML front-matter to enable sub-agent execution, optionally specifying `agent:` and `model:` for customized behavior.
- The forked skill executes in a five-phase process: parsing, sub-agent creation, isolated execution, result return, and cleanup.
- Hooks like `Stop` execute within the forked context, allowing conditional operations like Git commits only after successful skill completion.

## Frequently Asked Questions

### What is the difference between `context: fork` and running a regular skill?

A regular skill executes inline within the current conversation window, sharing the same context window and tool history with the main agent. Setting `context: fork` spawns a separate sub-agent with its own isolated memory window, so tool calls made by the skill do not appear in the main conversation history. According to the [`reports/claude-agent-command-skill.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-command-skill.md) documentation, only forked skills provide true context isolation.

### Can I use `context: fork` without specifying an agent type?

Yes. The `agent:` field is optional. If you omit it, Claude defaults to `general-purpose` for the sub-agent. As noted in [`CLAUDE.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md), the `agent` key only has meaning when `context: fork` is present; otherwise, it is ignored. You can also specify alternative agents like `fast-agent` for lighter-weight operations.

### Does a forked skill retain memory between invocations?

No. Each invocation of a forked skill creates a fresh sub-agent context that is discarded after execution completes. The repository's internal flow documentation describes a cleanup phase where the sub-agent's context is automatically discarded unless the skill explicitly persists data via hooks or external storage. For memory retention across calls, you would need to implement external state management or use the main agent's context without forking.