Skip to main content
skill CX Codex

agent-context-isolation — Claude Code skill: setup and use

agent-context-isolation is a Claude Code skill for routing background-agent results through files. It keeps full agent transcripts out of the main conversation context.

MIT ★ 3,951 updated 2026-01-26

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a claude-code
Open on GitHub

What agent-context-isolation does

The skill sets a file-based workflow for background agents: each agent saves its result, and the next one reads that file. Intermediate results go in .claude/cache/agents/; progress is tracked through system reminders and expected files rather than TaskOutput.

After agent work, the skill calls for running bun test and checking the tests. Its sample pipeline passes research, planning, and validation between agents as files, then has implementation read the validated plan. TaskOutput returns the agent’s full transcript, which can fill the main conversation context.

What it helps with

  • pass background-agent results through files
  • keep full agent transcripts out of the main context
  • connect research, planning, and implementation with file handoffs
  • check agent work by running tests

Example prompts for the agent

  • Send the research to a background agent and save its result to a file.
  • Set up planning and validation so each agent reads the previous result from a file.
  • Check the agent’s work with bun test without loading its transcript.

How to install agent-context-isolation

1Skills CLI (Vercel)

npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a claude-code

2Manually: put the files in place

~/.claude/skills/agent-context-isolation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agent-context-isolation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agent-context-isolation

How do I install agent-context-isolation in Claude Code?

Run npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a claude-code. The skill file is installed at ~/.claude/skills/agent-context-isolation/SKILL.md.

What does agent-context-isolation do?

It defines file-based coordination for background agents instead of sending their full transcripts into the main conversation. It also recommends checking agent work with bun test.

Why does the skill avoid TaskOutput?

TaskOutput returns the agent’s complete transcript. Reading it can consume the main context and push out details of the original request.

Source text

SKILL.md · MIT
---
name: agent-context-isolation
description: Agent Context Isolation
user-invocable: false
---

# Agent Context Isolation

Prevent agent output from polluting the main context window.

## Rules

### 1. Use Background Agents with File-Based Coordination
```
# RIGHT - background agent writes to file, main reads file
Task(subagent_type="...", run_in_background=true, prompt="... Output to: /path/to/file.md")

# WRONG - foreground agent dumps full transcript into main context
Task(subagent_type="...", run_in_background=false)
```

Background agents with `run_in_background=true` isolate their context. Have them write results to files in `.claude/cache/agents/<agent-type>/`.

### 2. Never Use TaskOutput to Retrieve Results
```
# WRONG - dumps entire transcript (70k+ tokens) into context
TaskOutput(task_id="<id>")
TaskOutput(task_id="<id>", block=true)

# RIGHT - check expected output files
Bash("ls -la .claude/cache/agents/<agent-type>/")
Bash("bun test")  # verify with tests
```

TaskOutput returns the full agent transcript. Always use file-based coordination instead.

### 3. Monitor Agent Progress via System Reminders
```
# System reminders come automatically:
# "Agent a42a16e progress: 6 new tools used, 88914 new tokens"

# To detect completion:
# - Watch for progress reminders to stop arriving
# - Poll for expected output files: find .claude/cache/agents -name "*.md" -mmin -5
# - Check task output file size growth: wc -c /tmp/claude/.../tasks/<id>.output
```

**Stuck agent detection:**
1. Progress reminders stop arriving
2. Task output file size stops growing
3. Expected output file not created after reasonable time

### 4. Verify with Tests, Not Output
After agent work:
1. Run the test suite directly: `bun test`
2. Report pass/fail counts
3. Only investigate failures if tests fail

### 5. File-Based Agent Pipeline Pattern
```
Research agent → .claude/cache/agents/oracle/output.md
                          ↓
Plan agent → .claude/cache/agents/plan-agent/output.md (reads research)
                          ↓
Validate agent → .claude/cache/agents/validate-agent/output.md (reads plan)
                          ↓
Implement agent → src/module.ts (reads validated plan)
```

Each agent reads the previous agent's file output, not TaskOutput.

## Why This Matters

Agent context isolation preserves the main conversation's context budget. Reading agent outputs via TaskOutput floods context, causing:
- Mid-conversation compaction
- Lost context about user's original request
- Repeated explanations needed

## Source
- Session where TaskOutput flooded 70k+ tokens into main context
- Session 2026-01-01: Successfully used background agents with file-based coordination for SDK Phase 3

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar skills

All skills for Agent setup: memory, context, orchestration →
context-discipline Rohit Ghumare The context-discipline rule sets limits for file reads, tool calls, and test-driven edits. It helps keep Claude Code from reopening unchanged files or polishing code after tests pass. CX Codex +1 ★ 2,966repo stars nemo-relay-instrument-context-isolation NVIDIA Corporation and Affiliates The nemo-relay-instrument-context-isolation skill keeps NeMo Relay scope stacks separate across concurrent work and preserves event ancestry as tasks cross execution boundaries. CX Codex +1 211installs run-affected-test-file-in-isolation-and-in-co-run-with-its-test- ZaxbyHub run-affected-test-file-in-isolation-and-in-co-run-with-its-test- is a Claude Code skill that makes the agent run tests in isolation and with sibling files after mock cleanup changes. CX Codex +1 ★ 539repo stars context-guard Gerui Lv context-guard is a Claude Code and Codex plugin that preserves requirements and verification evidence in long Codex tasks. It restores open items after context compaction and checks evidence before marking work complete. CX Codex ★ 1,596repo stars bmad-project-context bmad-code-org bmad-project-context is a Claude Code skill that builds, audits, and maintains verified agent instructions in AGENTS.md. It records past agent mistakes as explicit pitfalls. CX Codex +1 17,200installs qa-project-context kindlmann Scans your repo and generates .agents/qa-project-context.md with stack, test tools, and risk areas. Useful when configuring QA context before running other QA skills. CX Codex +1 1,800installs

From the same set161

The whole set →
proactive-delegation The proactive-delegation rule directs Claude Code to proactively hand off tasks to specialized subagents. It preserves the main context by detecting research, bug fixes, and parallel work automatically. CX Codex +1 ★ 3,951repo stars search-hierarchy The search-hierarchy skill picks a search tool based on whether a question concerns code structure, meaning, or an exact identifier. It helps locate a relevant file before reading it. CX Codex +1 ★ 3,951repo stars channel-capacity A skill for solving information-theory problems: calculating channel capacity, mutual information, and applying the Blahut-Arimoto algorithm. Use it when working with information theory, coding, or communication channels. CX Codex +1 ★ 3,951repo stars rudin-real-complex-analysis rudin-real-complex-analysis is a Claude Code skill for solving problems and checking proofs with Walter Rudin's Real and Complex Analysis textbook, a theorem tree, and Python scripts. CX Codex +1 ★ 3,951repo stars fields A skill for working with fields in abstract algebra. It verifies field axioms, computes minimal polynomials, and solves algebraic equations using Bash and Read tools. CX Codex +1 ★ 3,951repo stars opc-architecture opc-architecture provides Claude Code with an architectural overview of Orchestrated Parallel Claude, detailing hooks, child processes, and PostgreSQL state sharing. CX Codex +1 ★ 3,951repo stars modular-code The modular-code skill guides Python file splits around meaningful boundaries. Use it when a file mixes concerns or has become awkward to navigate and test. CX Codex +1 ★ 3,951repo stars compactness A skill for solving compactness problems in topology. Checks whether spaces are compact, applies the Heine-Borel and Tychonoff theorems, and computes consequences of compactness. CX Codex +1 ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open