Filesystem Context Patterns

Filesystem Context Patterns

Specialized expertise in using the filesystem to extend, persist, and share agent context beyond the conversation window. The filesystem is the most reliable mechanism for managing state across long sessions, between agents, and across session boundaries.

When to Use This Skill

Use this skill for:

• Tool outputs exceeding ~2,000 tokens (write to file instead of keeping in context)
• Tasks spanning multiple turns or sessions
• Multi-agent coordination requiring shared state
• Loading skills or configuration on demand
• Persisting plans, decisions, or analysis results
• Agent self-improvement through instruction updates

Trigger phrases: "write to file", "save context", "share between agents", "persist state", "scratch pad", "session file", "agent communication", "dynamic loading", "filesystem patterns"

What This Skill Does

Provides filesystem-based context management including:

• Scratch Pad: Writing intermediate results to files to free context space
• Plan Persistence: Storing plans that survive context resets
• Sub-Agent Communication: File-based message passing between agents
• Dynamic Skill Loading: Loading relevant skills on demand
• Terminal Persistence: Capturing terminal output for later reference
• Self-Modification: Agents updating their own instructions based on learnings

Instructions

Step 1: Select the Appropriate Pattern

Pattern Selection Guide:

Step 2: Scratch Pad Pattern

Purpose: Offload large intermediate results from context to filesystem, keeping only a compact reference in the conversation.

When to use: After generating or reading content larger than ~2,000 tokens that has been analyzed but may be needed for reference later.

Implementation:

## Scratch Pad Workflow

1. Agent generates or reads large content
2. Agent writes content to a scratch file:
   - Path: `tasks/scratch/[descriptive-name].md`
   - Include a header with purpose and timestamp
3. Agent states a compact summary in conversation
4. Later: agent re-reads the scratch file if needed

## File Naming Convention
tasks/scratch/
├── analysis-auth-module.md      # Codebase analysis results
├── search-results-user-api.md   # Search output saved for reference
├── diff-before-refactor.md      # Saved diff for comparison
└── tool-output-build-log.md     # Captured command output

Template for scratch files:

## Scratch: [Descriptive Title]
**Created**: [timestamp]
**Purpose**: [Why this was saved]
**Referenced by**: [What task/step uses this]

---

[Content]

Key rule: Always include a one-line summary in the conversation after writing the scratch file. The summary should contain enough information to decide whether to re-read the file.

Step 3: Plan Persistence Pattern

Purpose: Store structured plans in files so they survive context resets, session boundaries, and can be shared between agents.

When to use: Before starting any multi-step implementation; whenever a plan is approved.

Implementation:

## Plan Persistence Workflow

1. Create plan following the plan-before-code methodology
2. Write plan to: `tasks/plan-[feature-name].md`
3. Reference the plan file path throughout implementation
4. Update the plan file as steps complete (mark items done)
5. At session handoff, the plan file IS the continuity document

## Plan File Structure
tasks/
├── plan-auth-refactor.md        # Active implementation plan
├── plan-api-redesign.md         # Another active plan
├── completed/                   # Finished plans (for reference)
│   └── plan-db-migration.md
└── handoff-2026-02-24.md        # Session handoff document

Integration with plan-before-code: The plan file created in the planning phase becomes the source of truth throughout implementation. Instead of relying on the agent to "remember" the plan, have it re-read the file at each major step.

"Re-read tasks/plan-auth-refactor.md and proceed with the next
uncompleted step."

Step 4: Sub-Agent Communication Pattern

Purpose: Enable multiple agents to share state through filesystem rather than conversation context, avoiding the "telephone game" of context handoffs.

When to use: Multi-agent workflows, parallel research tasks, any situation where one agent's output feeds another agent's input.

Implementation:

## Sub-Agent Communication Workspace

tasks/agents/
├── shared/                       # Shared read-write space
│   ├── findings.md              # Accumulated research findings
│   ├── decisions.md             # Decisions log (append-only)
│   └── file-inventory.md       # List of all files under work
├── agent-research/              # Research agent's workspace
│   ├── output.md               # Research results
│   └── status.md               # Current status
├── agent-implementation/        # Implementation agent's workspace
│   ├── output.md               # Implementation results
│   └── status.md               # Current status
└── orchestrator/                # Orchestrator's coordination files
    ├── task-assignments.md      # Who is doing what
    └── integration-plan.md     # How to merge results

Communication Protocol:

1. Orchestrator writes task assignments to tasks/agents/orchestrator/task-assignments.md
2. Each agent reads its assignment, performs work, writes results to its workspace
3. Each agent updates shared/findings.md with key discoveries (append-only)
4. Orchestrator reads all agent outputs and integrates

Critical rules:

• shared/ files are append-only (agents add, never overwrite)
• Each agent has its own workspace (no cross-agent writes)
• Status files enable progress monitoring without reading full outputs
• Use structured formats (Markdown with consistent headers) for machine-readable content

Step 5: Dynamic Skill Loading Pattern

Purpose: Load skills and configuration on demand to keep the initial context lean and focused.

When to use: When the full skill catalog would consume too much context; when switching between task types mid-session.

Implementation:

## Dynamic Skill Loading Workflow

1. Start session with minimal context (core workflow skills only)
2. When a specific capability is needed:
   - Read the relevant SKILL.md file
   - Apply its instructions to the current task
   - The skill content enters context naturally through the file read
3. When switching to a different task type:
   - Read the new skill file
   - The previous skill's content naturally ages out of active attention

## Skill Discovery Paths
~/.codex/skills/                  # Global skills (installed by DevAI-Hub)
$CODEX_HOME/skills/                    # Project-specific skills
catalog/skills/[category]/[name]/ # Skill catalog (development reference)

Loading triggers:

• Security review needed → Read security-review/SKILL.md
• Compliance check needed → Read relevant compliance/[framework]/SKILL.md
• Performance optimization → Read performance-review/SKILL.md

Key principle: Do not pre-load all skills. Let the task determine which skills are relevant, and load them just-in-time.

Step 6: Terminal Persistence Pattern

Purpose: Capture terminal output (build logs, test results, command output) to files for later reference and analysis.

When to use: When command output is large, when you need to compare outputs across runs, or when test results need analysis.

Implementation:

## Terminal Persistence Workflow

1. Run command and capture output:
   - Write output to: `tasks/logs/[command]-[timestamp].txt`
   - Or use shell redirection: `npm test > tasks/logs/test-run.txt 2>&1`

2. Summarize the output in conversation:
   - "Tests: 45 passed, 3 failed. Details in tasks/logs/test-run.txt"

3. When analysis is needed:
   - Read the log file
   - Focus on specific sections (errors, warnings)
   - Write analysis to scratch pad

## Log File Organization
tasks/logs/
├── build-2026-02-24.txt         # Build output
├── test-run-latest.txt          # Most recent test run
├── lint-output.txt              # Linter results
└── deploy-staging.txt           # Deployment log

Step 7: Self-Modification Pattern

Purpose: Enable agents to update their own instructions based on discoveries made during sessions, creating a feedback loop that improves future sessions.

When to use: When the agent discovers a project convention, a gotcha, or a pattern that should persist across sessions.

Implementation:

## Self-Modification Targets

1. **AGENTS.md** (project-level):
   - Add discovered conventions: "All API routes use camelCase"
   - Add gotchas: "The auth module requires Node 18+"
   - Add workflow preferences: "Always run lint before commit"

2. **Memory files** (~/.codex/projects/[project]/memory/):
   - Store project-specific patterns
   - Record debugging insights
   - Track architectural decisions

3. **Skill files** (for skill developers):
   - Update skill instructions based on real-world usage
   - Add new patterns discovered through practice
   - Refine trigger phrases based on actual invocations

## Self-Modification Protocol
1. Agent discovers a pattern or convention
2. Agent verifies the pattern (check 2-3 examples in the codebase)
3. Agent proposes the update to the user
4. On approval: agent writes to the appropriate file
5. Future sessions benefit from the persisted knowledge

Safety guidelines:

• Always verify patterns against multiple examples before persisting
• Propose changes to the user before writing to AGENTS.md
• Memory files can be updated more freely (they are advisory, not directive)
• Never overwrite existing instructions without user approval

Best Practices

• Name files descriptively: analysis-auth-module.md not output.md
• Include timestamps: Files without dates become stale unknowingly
• Clean up scratch files: Delete or archive after the task completes
• Append, don't overwrite: For shared files, append new entries rather than replacing
• Reference paths explicitly: "See tasks/plan.md" is clearer than "see the plan file"
• Structured formats: Use Markdown with consistent headers so agents can parse content
• One purpose per file: A plan file, a findings file, and a decisions file are better than one giant file

Common Patterns

Pattern 1: Session State File

Situation: Long session needs checkpointing to prevent context loss.

Solution: Maintain a running state file that gets updated at each major milestone:

tasks/session-state.md:
- Current task and status
- Files modified (running list)
- Decisions made (append-only)
- Next steps (updated each milestone)

Pattern 2: Multi-Agent Workspace

Situation: Parallel research agents exploring different parts of the codebase.

Solution: Use the sub-agent communication workspace (Step 4) with:

• Each agent has its own output directory
• Shared findings file for cross-agent discovery
• Orchestrator integration plan for merging results

Pattern 3: Progressive Skill Loading

Situation: A code review task that starts with architecture analysis, then moves to security, then performance.

Solution: Load skills progressively as each phase begins:

1. Start: Read context-analysis/SKILL.md
2. Phase 2: Read security-review/SKILL.md
3. Phase 3: Read performance-review/SKILL.md
4. Final: Read final-report/SKILL.md

Each skill enters context fresh, at the point of maximum attention.

Quality Checklist

• Appropriate pattern selected for the situation
• Files named descriptively with timestamps where relevant
• Summaries provided in conversation after writing to files
• Shared files use append-only protocol
• Scratch files cleaned up after task completion
• Self-modification changes reviewed before persisting
• File paths referenced explicitly in conversation

Related Skills

• context-manager - Context fundamentals and attention budget management
• context-compression - Compression techniques that use filesystem patterns
• plan-before-code - Planning methodology (plans should be file-persisted)
• task-coordinator - Task coordination that benefits from file-based state

Version: 1.0.0 Last Updated: February 2026 Author: DevAI-Hub Attribution: Adapted from Agent-Skills-for-Context-Engineering (MIT License)

Iterative Refinement Strategy

This skill is optimized for an iterative approach:

1. Execute: Perform the core steps defined above.
2. Review: Critically analyze the output (coverage, quality, completeness).
3. Refine: If targets aren't met, repeat the specific implementation steps with improved context.
4. Loop: Continue until the definition of done is satisfied.