Lesson 19: Forked Context & Advanced Skills

Learning Objectives

After completing this lesson, you will be able to:

Understand forked sub-agent context
Use skill hot-reload (automatic in 2.1.x!)
Configure context forking in skill frontmatter
Set language preferences for responses
Specify agents in skills
Create advanced skills with full frontmatter

Prerequisites

Completed Lessons 1-18 - Core operations and agent teams
Skills experience - Lesson 5 recommended
Frontmatter knowledge - Basic YAML/JSON understanding

Estimated Time: 35 minutes

What is Forked Context?

Forked context creates an isolated environment for a sub-agent, allowing it to have its own conversation context while maintaining access to the parent's tools and files.

Concept: Process Fork

Think of forking like a process in your operating system:

Parent Process (Main Claude)
    │
    ├─ Main conversation context
    ├─ Full conversation history
    └─ Access to all tools
         │
         ▼
    fork()
         │
    ┌────┴────┐
    │         │
Child 1    Child 2
(Forked)   (Forked)
    │         │
    └─ New context   └─ New context
    └─ Clean slate   └─ Clean slate
    └─ Inherits      └─ Inherits
       tools            tools

Why Use Forked Context?

Benefits:

Clean slate - Fresh context without parent conversation overhead
No interference - Parent context doesn't bias the sub-agent
Focused execution - Sub-agent sees only what it needs
Token efficiency - Doesn't duplicate conversation history
Predictable behavior - Sub-agent starts fresh each time

When to use:

Skills that should execute independently
Commands that need clean context
Sub-agents doing specific tasks
Reducing token usage for repetitive tasks

When NOT to use:

Tasks that need conversation history
Context-dependent operations
Multi-step workflows requiring continuity

Skill Hot-Reload (NEW in 2.1.x!)

What is Hot-Reload?

Before 2.1.x: You had to restart Claude Code to see skill changes.

2.1.x and later: Skills are automatically reloaded when modified!

How It Works

Automatic discovery:

.claude/skills/
├── refactor.md
├── test.md
└── deploy.md

[You edit refactor.md]

Claude Code detects file change → Reloads skill instantly → Skill ready to use

Supported locations:

~/.claude/skills/ - User-level skills
.claude/skills/ - Project-level skills
Nested .claude/skills/ - Subdirectory skills

Hot-Reload in Action

Before (old behavior):

# Edit skill file
vim ~/.claude/skills/refactor.md

# Restart Claude Code
exit
claude

# Now skill is updated

After (2.1.x behavior):

# Edit skill file
vim ~/.claude/skills/refactor.md

# Skill is immediately available!
# No restart needed

Real-time example:

You: Edit the test skill to include coverage reporting

[You open ~/.claude/skills/test.md]
[Add coverage reporting instructions]
[Save file]

Claude: I've detected an update to the test skill.
The skill has been reloaded and is ready to use.

You: /test

Claude: [Running updated test skill with coverage reporting]

Hot-Reload Best Practices

Test skill changes immediately

Edit skill → Save → Run skill → Verify

Iterate quickly

# Development loop
vim ~/.claude/skills/feature.md  # Edit
/feature                          # Test
vim ~/.claude/skills/feature.md  # Edit again
/feature                          # Test again

No restart needed
- Skills reload automatically
- Keep Claude Code running
- Focus on skill development

Configuring Forked Context

The `context` Frontmatter Field

Skills can specify context: fork in their frontmatter:

---
context: fork
---

# Skill Name

This skill runs in a forked context with clean slate.

Forked vs. Inherited Context

Inherited context (default):

---
name: analyze-with-history
---

# Analyze With History

This skill sees the full conversation history.

Use when: Context from previous messages is important

Forked context:

---
name: clean-task
context: fork
---

# Clean Task

This skill starts with a fresh context.

Use when: You want an isolated, clean execution

Practical Examples

Example 1: Code Review Skill

---
name: code-review
context: fork
description: Review code without bias from conversation
---

# Code Review

You are a code reviewer. Review the provided code objectively.

Guidelines:
- Check for bugs and edge cases
- Verify error handling
- Assess performance
- Suggest improvements

Review this code:
{{code}}

Do not reference previous conversation context. Review only what you see.

Why forked? The review should be unbiased, not influenced by earlier discussions.

Example 2: Debug Skill

---
name: debug
context: fork
description: Debug issues with fresh perspective
---

# Debug

You are a debugger. Investigate the reported issue.

Issue: {{issue}}

Steps to debug:
1. Reproduce the issue
2. Identify root cause
3. Propose solution
4. Verify fix

Start fresh - don't assume from previous context.

Why forked? Avoid assumptions from earlier debugging attempts.

Example 3: Deploy Skill

---
name: deploy
description: Deploy to production (uses conversation context)
---

# Deploy

You are deploying to production.

Context from our conversation:
- We've tested the feature
- All tests pass
- Code is reviewed

Deploy following our standard process.

Why NOT forked? The deployment depends on previous testing and review context.

Language Settings

Configuring Response Language

As of 2.1.0, you can configure Claude's response language.

Method 1: Settings file

{
  "language": "japanese"
}

Method 2: Environment variable

export CLAUDE_LANGUAGE="spanish"
claude

Method 3: Skill frontmatter

---
name: francais
language: french
---

# Compétence en Français

Réponds toujours en français.

Supported Languages

Any language that Claude understands:

English (default)
Spanish
French
German
Italian
Portuguese
Dutch
Japanese
Chinese (Simplified)
Chinese (Traditional)
Korean
Russian
Arabic
Hindi
And many more...

Language Examples

Japanese skill:

---
name: refactor-jp
language: japanese
description: 日本語でリファクタリング
---

# リファクタリング

日本語でコードをリファクタリングします。

{{code}}

Chinese skill:

---
name: debug-zh
language: chinese
description: 用中文调试代码
---

# 调试

用中文帮你调试代码。

问题：{{issue}}

Multi-language support:

You: /refactor-jp

Claude: このコードをリファクタリングしましょう。
[Limits responses to Japanese]

You: /debug-zh

Claude: 我来帮你调试这个问题。
[Limits responses to Chinese]

Agent Specification in Skills

The `agent` Field

Skills can specify which agent type to use:

---
agent: general-purpose
model: claude-haiku-4-5
---

# Quick Task

Use Haiku for this fast, simple task.

Agent Types

Available agent types:

general-purpose - Default, all tools available
bash - Command execution specialist
plan - Planning and design specialist
explore - Codebase exploration specialist
Custom agents from .claude/agents/

Agent + Model Combinations

Fast execution (Haiku):

---
name: quick-fix
agent: general-purpose
model: claude-haiku-4-5
description: Quick fixes with Haiku
---

# Quick Fix

Apply this simple fix quickly.

Fix: {{fix_description}}

Balanced (Sonnet):

---
name: feature
agent: general-purpose
model: claude-sonnet-4-5
description: Feature implementation
---

# Feature

Implement this feature with Sonnet.

Feature: {{feature_description}}

Complex reasoning (Opus):

---
name: architecture
agent: plan
model: claude-opus-4-5
description: Architecture design with Opus
---

# Architecture

Design the architecture for this complex system.

Requirements: {{requirements}}

Bash specialist:

---
name: run-tests
agent: bash
description: Run test suite
---

# Run Tests

Execute the test suite using bash commands.

Test suite: {{test_path}}

Advanced Skill Frontmatter

Complete Frontmatter Reference

---
# Basic
name: skill-name
description: One-line description
category: development

# Context
context: fork  # or "inherit" (default)

# Agent
agent: general-purpose
model: claude-sonnet-4-5

# Language
language: english

# Permissions
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash

# Hooks
hooks:
  pre-tool: ./scripts/check.sh
  post-tool: ./scripts/notify.sh

# Input (for user-invocable skills)
arguments:
  - name: file
    description: File to process
    required: true

# Metadata
user-invocable: true
version: "1.0.0"
author: Your Name
tags:
  - refactoring
  - testing
---

# Skill Content

The skill instructions go here.

YAML-Style Lists (NEW in 2.1.x!)

Old style (JSON):

allowed-tools: ["Read", "Edit", "Write"]

New style (YAML):

allowed-tools:
  - Read
  - Edit
  - Write

Both work, but YAML is cleaner and more readable.

Once-Only Hooks (NEW in 2.1.x!)

---
hooks:
  pre-tool:
    command: ./scripts/once.sh
    once: true  # Only run once per session
---

Advanced Examples

Example 1: Complete refactor skill

---
name: refactor-complete
description: Comprehensive code refactoring
category: development
context: fork
agent: general-purpose
model: claude-sonnet-4-5
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
user-invocable: true
tags:
  - refactoring
  - cleanup
  - optimization
---

# Complete Refactor

Comprehensively refactor the provided code.

## Analysis Phase
1. Understand code purpose
2. Identify issues:
   - Bugs
   - Performance problems
   - Code smells
   - Security vulnerabilities

## Refactoring Phase
1. Fix identified issues
2. Improve structure
3. Add documentation
4. Optimize performance

## Verification Phase
1. Run tests
2. Verify functionality
3. Check for regressions

Code to refactor:
{{code}}

Start with a fresh perspective - don't assume from previous context.

Example 2: Multi-language deploy skill

---
name: deploy
description: Deploy application
category: operations
language: japanese
agent: bash
allowed-tools:
  - Bash
hooks:
  pre-tool:
    command: ./scripts/pre-deploy-check.sh
  post-tool:
    command: ./scripts/post-deploy-notify.sh
arguments:
  - name: environment
    description: Target environment (staging/production)
    required: true
---

# デプロイ (Deploy)

アプリケーションをデプロイします。

環境: {{environment}}

手順:
1. 事前チェック
2. ビルド
3. デプロイ
4. 事後検証
5. 通知

Practical Example: Building Advanced Skills

Let's build a comprehensive skill using all these features.

Scenario: Automated Testing Skill

Requirements:

Forked context (clean testing environment)
Use Haiku for speed
Bash agent for test execution
Hot-reload for quick iteration
Pre/post hooks

Step 1: Create initial skill

mkdir -p ~/.claude/skills
vim ~/.claude/skills/auto-test.md

Step 2: Write skill with frontmatter

---
name: auto-test
description: Automated testing with Haiku
category: testing
context: fork
agent: bash
model: claude-haiku-4-5
allowed-tools:
  - Bash
  - Read
hooks:
  pre-tool:
    command: npm run lint
  post-tool:
    command: ./scripts/test-notify.sh
user-invocable: true
tags:
  - testing
  - automation
---

# Automated Testing

Run the automated test suite using Haiku for speed.

## Pre-check
Linting is run automatically before tests.

## Test Execution
Run the full test suite:
```bash
npm test

Analysis

Analyze results:

Count passed/failed tests
Identify failing tests
Summarize issues

Reporting

Send notification with results.

Start fresh - use only the test results, not previous context.

**Step 3: Test and iterate (hot-reload in action)**

```bash
# Run skill
/auto-test

[Skill runs, notices missing notification script]

# Edit skill to fix
vim ~/.claude/skills/auto-test.md

# Add error handling for missing script
[Save - skill auto-reloads!]

# Run again
/auto-test

[Skill now works correctly]

Step 4: Enhance skill

# Add coverage reporting
vim ~/.claude/skills/auto-test.md

# Add coverage instructions
[Save - auto-reloads immediately]

# Test enhanced version
/auto-test

[Now includes coverage report]

✅ Check Your Understanding

What does forked context do?
- Duplicates the conversation history
- Creates a clean, isolated context
- Shares context with parent
- Requires more tokens
True or False: You need to restart Claude Code to see skill changes in 2.1.x.
- True
- False (hot-reload is automatic!)
How do you set the response language in a skill?
- lang: spanish
- language: spanish
- locale: spanish
- responseLanguage: spanish
What field specifies the agent type in a skill?
- agentType
- agent
- type
- useAgent
Which context mode is best for unbiased code review?
- Inherited context
- Forked context
- No context
- Shared context

Answers: 1-b, 2-False, 3-b, 4-b, 5-b

Summary

In this lesson, you learned:

Forked context - Isolated sub-agent environments
Skill hot-reload - Automatic in 2.1.x!
Language settings - Configure response language
Agent specification - Choose agent type and model
Advanced frontmatter - Complete skill configuration

Next Steps

In Lesson 20: 2.1.x Advanced Features, you'll learn:

Wildcard permission patterns
Enhanced hooks system
Session forking and rewind
External editor support
Enhanced vim motions
Task dependencies

Learning Objectives​

Prerequisites​

What is Forked Context?​

Concept: Process Fork​

Why Use Forked Context?​

Skill Hot-Reload (NEW in 2.1.x!)​

What is Hot-Reload?​

How It Works​

Hot-Reload in Action​

Hot-Reload Best Practices​

Configuring Forked Context​

The context Frontmatter Field​

Forked vs. Inherited Context​

Practical Examples​

Language Settings​

Configuring Response Language​

Supported Languages​

Language Examples​

Agent Specification in Skills​

The agent Field​

Agent Types​

Agent + Model Combinations​

Advanced Skill Frontmatter​

Complete Frontmatter Reference​

YAML-Style Lists (NEW in 2.1.x!)​

Once-Only Hooks (NEW in 2.1.x!)​

Advanced Examples​

Practical Example: Building Advanced Skills​

Scenario: Automated Testing Skill​

Analysis​

Reporting​

✅ Check Your Understanding​

Summary​

Next Steps​

Further Reading​