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
npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a claude-codeWhat 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 testwithout 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-code2Manually: put the files in place
~/.claude/skills/agent-context-isolation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/agent-context-isolation/
1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a codex2Manually: put the files in place
.agents/skills/agent-context-isolation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a cursor2Manually: put the files in place
.cursor/skills/agent-context-isolation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install parcadei/Continuous-Claude-v3 .claude/skills/agent-context-isolation2Manually: put the files in place
.github/skills/agent-context-isolation/SKILL.md1Skills CLI (Vercel)
npx skills add parcadei/Continuous-Claude-v3 --skill agent-context-isolation -a gemini-cli2Platform CLI
gemini skills install https://github.com/parcadei/Continuous-Claude-v3 --path .claude/skills/agent-context-isolationManually: put the files in place
.devin/skills/agent-context-isolation/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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