Engineer Context with Filesystem Persistence

This skill packages patterns for filesystem-based context engineering: using the filesystem as a persistent, searchable layer so agents can store and retrieve effectively unlimited context without carrying everything in the context window. It documents six patterns: using the filesystem as a scratch pad for large tool outputs, writing outputs over a token threshold to a file and returning a summary plus a file reference instead of the raw content; plan persistence, writing a structured plan such as a YAML file with objective, status, and steps that the agent re-reads to stay oriented on long-horizon tasks; sub-agent communication via the filesystem, where sub-agents write findings directly to files a coordinator reads instead of passing messages through summarization hops; dynamic skill loading, keeping only skill names and brief descriptions in static context and loading full skill files only when relevant; terminal and log persistence, syncing terminal output to files so agents can grep for errors instead of loading entire histories; and learning through self-modification, where agents write learned preferences to their own instruction files for later sessions to load, with an explicit caution that this needs guardrails against accumulating incorrect instructions.

Activate it when tool outputs are bloating the context window, agents need to persist state across long trajectories, sub-agents must share information without direct message passing, tasks need more context than fits in the window, you're building agents that learn and update their own instructions, implementing scratch pads for intermediate results, or making terminal output and logs accessible to agents. Avoid it when tasks complete in a single turn, context already fits comfortably in the window, latency is critical since file I/O adds overhead, or the model in use is not capable of using filesystem tools.

The core mechanism writes tool output over a threshold to a scratch file and returns a short summary plus file path instead of the raw content:

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

    # Write to scratch pad
    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)

    # Return reference instead of content
    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

The agent then uses grep or read_file with line ranges for targeted retrieval rather than loading the whole file. The skill documents ls/list_dir, glob, grep, and ranged read_file as the core filesystem search toolkit, and recommends organizing files into scratch/, memory/, skills/, and agents/ directories with consistent naming and timestamps for disambiguation.

It names five related skills in the same collection it expects to connect to: context-optimization (filesystem offloading as a form of observation masking), memory-systems (filesystem-as-memory as a simple memory layer), multi-agent-patterns (sub-agent file workspaces for isolation), context-compression (file references as lossless compression), and tool-design (tools should return file references for large outputs).

Engineers building agents or multi-agent systems that run long tasks, generate large tool outputs, or need agents to remember things across sessions, who want a concrete, measured pattern for offloading bulk context to files instead of growing the prompt indefinitely, with an explicit reminder to measure token savings rather than assume them and to add cleanup for scratch files so they don't grow unbounded.