Agent-Skills.md

Agent Skills: Context Fork Skill

Demonstrates forked context execution. This skill runs in an isolated sub-agent context with its own conversation history and tool access.

UncategorizedID: louloulin/claude-agent-sdk/context-fork-skill

Repository

louloulin/claude-agent-sdk
louloulinLicense: MIT
123

Install this agent skill to your local

pnpm dlx add-skill https://github.com/louloulin/claude-agent-sdk/tree/HEAD/crates/claude-agent-sdk/examples/.claude/skills/context-fork-skill

Skill Files

Browse the full folder contents for context-fork-skill.

Download Skill

Loading file tree…

crates/claude-agent-sdk/examples/.claude/skills/context-fork-skill/SKILL.md

Skill Metadata

Name
context-fork-skill
Description
Demonstrates forked context execution. This skill runs in an isolated sub-agent context with its own conversation history and tool access.

Context Fork Skill

This skill demonstrates the context: fork feature, which allows a skill to run in an isolated sub-agent context with its own conversation history and state.

What is Forked Context?

When a skill uses context: fork, it:

  1. Creates a new sub-agent: A separate agent instance is created
  2. Isolates conversation history: Has its own independent context
  3. Provides clean state: No contamination from the main conversation
  4. Can specify agent type: Uses the agent field to determine sub-agent behavior

When to Use Forked Context

✅ Good Use Cases

  1. Complex Multi-Step Operations

    • Long-running analyses that shouldn't clutter main conversation
    • Multi-phase processing with intermediate states

  2. Isolated Testing

    • Test code without affecting main context
    • Experiment with different approaches

  3. Specialized Agent Behavior

    • Need specific agent type (Plan, Explore, etc.)
    • Different tool access patterns

  4. State Management

    • Keep temporary state isolated
    • Prevent unintended side effects

❌ Avoid When

  1. Simple one-shot tasks (overhead not worth it)
  2. Need to share results immediately (forked context is isolated)
  3. Real-time collaboration required (context is separate)

Configuration

Skill Metadata

context: fork           # Enables forked context
agent: general-purpose  # Specifies agent type

Available Agent Types

  • general-purpose: Default agent for general tasks
  • Plan: Planning and design focused
  • Explore: Codebase exploration and analysis
  • code-reviewer: Code review specialist
  • custom: Custom agents defined in .claude/agents/

Testing Forked Context

Test 1: Basic Isolation

Ask me to perform a complex analysis:

Analyze this codebase and create a detailed report

Behavior:

  1. A new sub-agent is created
  2. The analysis runs in isolation
  3. The main conversation stays clean
  4. Results are returned when complete

Test 2: Conversation History

Test that the forked context has separate history:

First, tell me your name in the forked context
Then ask in the main conversation what we discussed

Expected: The main conversation won't see the forked context's internal messages

Test 3: Different Agent Types

Test with different agent types:

# For planning tasks
context: fork
agent: Plan

# For exploration
context: fork
agent: Explore

# For code review
context: fork
agent: code-reviewer

Advanced Features

1. Combining with Hooks

Forked context works with hooks:

context: fork
agent: general-purpose
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Forked context: Running Bash'"

2. Tool Restrictions

Limit tools in forked context:

context: fork
agent: general-purpose
allowed_tools:
  - Read
  - Grep
  # No Write - read-only analysis

3. Model Selection

Use specific model in forked context:

context: fork
agent: general-purpose
model: claude-sonnet-4-20250514

Comparison: Forked vs Non-Forked

| Aspect | Non-Forked (Default) | Forked Context | |--------|---------------------|----------------| | Conversation History | Shared with main | Separate/isolated | | State | Global state | Independent state | | Tool Access | Inherits from main | Configured independently | | Context Window | Uses main context | Separate context window | | Overhead | None | Sub-agent creation | | Use Case | Simple tasks | Complex/isolated tasks |

Implementation Details

Architecture

Main Conversation
    ↓
    User requests task using context-fork-skill
    ↓
Skill Engine
    ↓
    Detects context: fork
    ↓
Sub-Agent Factory
    ↓
    Creates new agent instance
    ↓
Forked Context
    ↓
    Executes task in isolation
    ↓
    Returns results
    ↓
Main Conversation (receives results)

Memory Considerations

Forked context:

  • ✅ Has its own context window
  • ✅ Doesn't compete with main context for tokens
  • ⚠️ Uses additional memory (sub-agent instance)
  • ⚠️ Results still consume tokens when returned

Performance

Forked context overhead:

  • Creation: ~100-200ms
  • Execution: Same as normal (no penalty)
  • Cleanup: ~50ms

Total overhead: ~150-250ms per invocation

Best Practices

DO ✅

  1. Use for complex tasks

    • Multi-step analyses
    • Long-running operations
    • Stateful processing

  2. Choose appropriate agent

    • Plan for design tasks
    • Explore for code analysis
    • general-purpose for general tasks

  3. Combine with tool restrictions

    • Read-only for analysis
    • Specific tools for specific tasks

  4. Document the isolation

    • Explain why forked context is used
    • Clarify what's isolated

DON'T ❌

  1. Don't use for simple tasks

    • One-shot queries don't need isolation
    • Adds unnecessary overhead

  2. Don't forget about isolation

    • Results need to be explicitly returned
    • Can't access main conversation state

  3. Don't overuse

    • Each fork consumes resources
    • Multiple concurrent forks can be expensive

  4. Don't assume shared state

    • Forked context starts fresh
    • No memory of previous interactions

Testing Checklist

Verify forked context behavior:

  • [ ] Sub-agent is created
  • [ ] Conversation history is isolated
  • [ ] Agent type is respected
  • [ ] Tool restrictions work
  • [ ] Results are returned correctly
  • [ ] No contamination of main context
  • [ ] Cleanup happens after completion
  • [ ] Works with hooks
  • [ ] Works with model selection

Troubleshooting

Fork Not Creating

Problem: Skill runs in main context

Solutions:

  1. Verify context: fork is in YAML frontmatter
  2. Check YAML syntax (no tabs, proper indentation)
  3. Ensure agent field is specified

Wrong Agent Type

Problem: Uses default agent instead of specified one

Solutions:

  1. Check agent name spelling
  2. Verify agent exists (for custom agents)
  3. Use built-in agent names (general-purpose, Plan, Explore)

Results Not Returned

Problem: Forked context completes but no results

Solutions:

  1. Ensure skill returns output
  2. Check for errors in forked context
  3. Verify execution completed successfully

Examples

Example 1: Code Analysis

---
name: deep-code-analysis
description: Perform deep code analysis in isolation
context: fork
agent: Explore
allowed_tools:
  - Read
  - Grep
  - Glob
---

Usage:

Analyze the authentication system deeply

Example 2: Security Audit

---
name: security-audit
description: Run security audit in isolated context
context: fork
agent: general-purpose
allowed_tools:
  - Read
  - Grep
  - Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Security audit: Executing command'"
---

Example 3: Planning Task

---
name: architecture-planner
description: Create architecture plan in isolation
context: fork
agent: Plan
---

Usage:

Create a detailed plan for refactoring the payment system

Summary

Forked context provides:

  • ✅ Isolated execution environment
  • ✅ Separate conversation history
  • ✅ Configurable agent types
  • ✅ Clean state management
  • ✅ No contamination of main context

Use when you need isolation, complex processing, or specialized agent behavior.

Version: 1.0.0 Last Updated: 2026-01-10 Maintainer: SDK Team