Agent skill

context-topology

Master Claude Code's context primitives (Skill, Task, Command) and orchestration patterns. Use when designing agent workflows, understanding why some patterns work while others fail (e.g., Task→Task is forbidden but Skill→Skill is allowed), or implementing Chain of Experts architectures. Not for writing prompts or content generation.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/context-topology

SKILL.md

Context Topology & Orchestration Patterns

Core Insight: Optimal orchestration is not about writing better prompts—it's about managing context topology. Claude Code is a modular network of agents, not a single chat.

The Four Primitives

Claude Code provides four primitives for delegation, each with a distinct Memory Mode:

Primitive Memory Mode Description
Skill Shared Content injects into current conversation. Preserves context, sees full history. Use for heuristics, code standards, "How-To" guides.
Skill + context: fork Isolated Runs in a clean context (forked from parent). Only sees CLAUDE.md and skill content. Use for unbiased specialists (Linter, Security Auditor).
Task Forked Creates a new agent instance with full isolation. System prompt = subagent body. Keeps "noise" (bash logs, diffs) out of main context.
Command Injected Entry point using @file or !cmd syntax for deterministic runtime state.

Syntax Summary

markdown
# Skill (shared context)
Skill(skill-name)

# Skill (isolated context)
<!-- In SKILL.md frontmatter: -->
---
context: fork
agent: general-purpose
skills:
  - helper-skill
---

# Task (forked agent)
Task(subagent-name)
Task(subagent-name, run_in_background=True)

# Command (injected)
!`git status`
@path/to/file.md

The Recursion Loophole

Critical Constraint

Pattern Status Why
Task → Task FORBIDDEN Recursion blocker prevents infinite agent spawning
Skill(fork) → Skill(fork) ALLOWED Skill loophole bypasses recursion limit

Why This Matters

When you need more than 3 levels of depth:

❌ WRONG: Task → Task (crashes at level 2)
✅ RIGHT: Task → Skill(fork) → Skill(fork) → Skill(fork)

The Chain of Experts pattern exploits this loophole:

Level 1 (Main):     Conductor. Holds TaskList state.
Level 2 (Forked):   Architect. Researches, creates JSON plan.
Level 3 (Forked):   Implementer. Executes edits, runs tests.
Level 4 (Forked):   Verifier. Validates output, returns pass/fail.

Chain of Experts Pattern

A multi-phase workflow that keeps each phase isolated from context pollution.

Architecture

┌─────────────────────────────────────────────────────┐
│ Main Agent (Conductor)                              │
│ - Holds TaskList state                             │
│ - Spawns Level 2 with Task()                        │
│ - Receives summary, not full logs                   │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ Level 2: Architect (Skill + context: fork)          │
│ - agent: Plan (read-only, cannot edit)              │
│ - Reads codebase, creates execution plan            │
│ - Returns: JSON or markdown plan                    │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ Level 3: Implementer (Task or Skill + context: fork)│
│ - agent: general-purpose                            │
│ - Executes plan, performs edits                     │
│ - Runs tests, fixes failures internally             │
│ - Returns: 5-line summary                           │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│ Level 4: Verifier (Skill + context: fork)           │
│ - agent: Explore or general-purpose                 │
│ - Validates work without implementation bias        │
│ - Returns: Pass/Fail with evidence                  │
└─────────────────────────────────────────────────────┘

When to Use Each Level

Level Use When Agent Type
2 (Architect) Need research, planning, or design decisions agent: Plan
3 (Implementer) Heavy editing, test running, complex execution agent: general-purpose
4 (Verifier) Need unbiased validation, security scan, lint agent: Explore or agent: general-purpose

Advanced Patterns

1. Background Auditor Pattern

Run parallel workflows while main agent continues work:

python
# Main agent continues UI changes
Task("security-audit", run_in_background=True)

# When Task finishes, it "interrupts" with summary

Use when:

  • Long-running CI/CD scripts
  • Security scans on entire repo
  • Parallel feature work and verification

2. Skill Sandwich Pattern

Verification loop where the worker checks its own work:

Main → Skill(define_criteria) → Task(implement) → Skill(fork:linter) → Main

Why it works: Level 3 (Linter) has zero knowledge of implementation struggle—no bias from seeing "I've been trying for 20 messages."

3. Dispatcher Skill Pattern

A skill that analyzes requests and routes to appropriate handlers:

yaml
---
name: dispatcher
description: "Analyzes requests and routes to appropriate handler. Use when unsure which primitive to use or when work needs distribution."
context: fork
agent: general-purpose
---

Logic:

  1. Analyze request complexity
  2. Select primitive (Task vs Skill vs Skill(fork))
  3. Spawn appropriate handler
  4. Return result to parent

4. Context Compaction Defense

Since Claude Code auto-compacts at 95% capacity, move procedural knowledge to modular rules:

markdown
# Instead of in a skill:
"Use this pattern for testing..."

# Put in .claude/rules/testing.md:
- Test patterns, assertions, coverage targets

Result: Modular rules load into EVERY subagent and forked skill by default.

Decision Matrix

Which Primitive for the Goal?

Goal Primitive Why
Exploration Skill(context: fork) + agent: Explore Fastest, cheapest, cannot break code
High-volume edits Task(subagent) Keeps main context clean
Strict compliance Skill(context: fork) No context contamination
User shortcuts Command @ and ! for determinism
Safety enforcement Hooks Survives across subagents

Which Agent Type for Forked Skills?

Agent Type Capabilities Restrictions Use When
Explore Read-only tools No Write, Edit, Task Research, code analysis
Plan Read-only tools No Write, Edit Creating execution plans
general-purpose All tools None Heavy lifting, editing
Bash Terminal commands Shell operations only Git ops, builds, scripts

When to Fork Context?

Scenario Context Mode Example
Need unbiased specialist context: fork Linter, Security Auditor
Heavy lifting (many edits) Task() Refactoring 20 files
Reusable worker Skill(fork) "Extract data from file"
Keep main context clean Task() Long test runs with logs

Common Anti-Patterns

Anti-Pattern 1: Task→Task (True Subagent Nesting)

markdown
❌ WRONG:
Task(subagent-a)  # Level 1 (true subagent spawn)
→ Task(subagent-b)  # BLOCKED: subagents cannot spawn subagents

⚠ IMPORTANT DISTINCTION:

  • Task() spawns true subagents (recursion blocked)
  • Skill(context: fork) runs inline with context isolation (ALLOWED to chain)

Anti-Pattern 2: Missing context: fork

markdown
❌ WRONG:
---
# Missing context: fork - sees parent history
name: linter
---
Use the Bash tool to run linting...

Problem: Linter sees previous implementation attempts—biased validation.

Pattern: Chain of Experts (Valid)

markdown
✅ CORRECT:
Skill(skill-a)                    # Phase 1: Setup (shared context)
→ Skill(skill-b, context: fork)   # Phase 2: Analysis (isolated)
→ Skill(skill-c, context: fork)   # Phase 3: Validation (isolated)

Benefit: First skill establishes shared context, subsequent forked phases run with isolation while maintaining bidirectional information flow. Skill(context: fork) runs inline (not true subagent), allowing chaining.

⚠ Best Practice: First skill should be non-forked (shared context) to anchor the chain. All-forked chains may lose the return path to the original context.

⚠ Note: Use judiciously—each fork has overhead. Reserve for multi-phase workflows requiring clean separation.

Anti-Pattern 4: All-Inline Skill Chain

markdown
❌ WRONG:
Skill(skill-a)  # All shared context
→ Skill(skill-b)
→ Skill(skill-c)

Problem: Zero forked skills means context injection only—no reliable return path to original skill. Primitives inject new context but don't maintain chain coherence. Execution may not return to skill-a as expected.

Fix: First skill shared context, subsequent skills forked:

markdown
✅ CORRECT:
Skill(skill-a)                    # Anchor with shared context
→ Skill(skill-b, context: fork)   # Forked isolation
→ Skill(skill-c, context: fork)   # Forked isolation

Anti-Pattern 5: Fork for trivial tasks

markdown
❌ WRONG:
---
context: fork
---
What is 2 + 2?

Problem: Fork has overhead. Inline execution is cheaper.

Frontmatter Reference

Skill Frontmatter

yaml
---
name: skill-name              # Max 64 chars, lowercase, hyphens
description: "When to use. Not for exclusions."
context: fork                 # Omit for shared context
agent: general-purpose        # Only if context: fork
skills:                       # Preload skills for forked context
  - helper-skill
allowed-tools:                # Reactive constraint (optional)
  - Read
  - Write
---

Command Frontmatter

yaml
---
description: "When to use this command."
---

Memory Hierarchy

What loads into which context:

Context Loads
Main CLAUDE.md, CLAUDE.local.md, .claude/rules/*, loaded skills
Task (subagent) CLAUDE.md, .claude/rules/*, subagent body
Skill(fork) CLAUDE.md, .claude/rules/*, skill content
Command @file content, !cmd output

Key insight: Task and Skill(fork) do NOT see the parent conversation. This is the isolation mechanism.

Summary

  1. Choose primitive by memory mode: Shared (Skill), Isolated (Skill+fork), Forked (Task), Injected (Command)
  2. Exploit the recursion loophole: Task→Task forbidden, Skill→Skill allowed
  3. Chain Experts for clean contexts: Architect → Implementer → Verifier
  4. Use Task for heavy lifting: Keeps main context free of noise
  5. Use Skill(fork) for unbiased specialists: Linters, validators, auditors
  6. Use Commands for deterministic entry points: @file, !cmd injection

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results