Filesystem Context Engineering
Move large, durable, or shared agent context into files and retrieve it selectively when needed.
The documentation surfaces cleanup, race-condition, path, and self-modification risks and recommends isolation, validation, and retention policies. However, examples perform file writes/deletes without confirmation, persist self-modifications, and reference code uses shell=True for arbitrary command execution, with no explicit permission boundaries, sensitive-data policy, or rollback, so points are deducted.
SKILL.md, the reference implementation, and scripts/filesystem_context.py describe understandable core paths, but coverage is inconsistent across them. Error handling, concurrency safety, file-size checks, and failure feedback are limited, and no dedicated tests cover this skill's key paths. Static calibration therefore limits the score to 10 or below, with deductions applied.
Activation scenarios, use cases, and boundaries with adjacent skills are relatively clear, covering scratchpads, plan persistence, and multi-agent file coordination. However, the skill depends on host filesystem capabilities and does not clearly define input/output contracts, non-fit environments, or Chinese-language support, so it is not full marks.
The material is well structured, with progressive disclosure, patterns, examples, gotchas, references, version, dates, author information, and an MIT license. Maintenance ownership, changelog/update path, and dependency-installation guidance are incomplete, and some external resources are named without source details, so points are deducted.
The skill supplies directly adaptable Python implementations for file offloading, plan persistence, and tool-output handling, covering the core use cases. However, several patterns described in SKILL.md are not implemented in the companion script, and integration, permission design, and validation remain necessary. Static calibration caps effectiveness at 7, so points are deducted.
There is committed source code, documentation, examples, and repository-level CI/validation, but no evidence that CI specifically tests filesystem-context key paths. External research and performance claims are not independently corroborated at the skill level. This supports only limited auditability; static calibration caps the score at 5, so points are deducted.
- The reference TerminalCapture uses shell=True; untrusted command input could enable command injection, so command sources and permissions must be restricted.
- Scratch cleanup deletes old files and examples write to relative paths; add confirmation, directory isolation, sensitive-data exclusions, retention policy, and recoverable backups.
- The companion script implements only part of the documented patterns, and no dedicated skill tests are shown; add tests for boundaries, concurrency, path failures, and data integrity.
What does this skill do, and when should you use it?
This Agent Skill presents filesystem-backed context management for tool-output offloading, durable plans, multi-agent handoffs, terminal logs, and dynamic skill loading. It recommends directory discovery, globbing, grep, and range-based reads so agents can retrieve only relevant information instead of keeping everything in the prompt. It also covers file organization, cleanup policies, concurrent access, stale references, and validation for self-modifying files. It is most useful for agent systems whose work spans multiple turns or produces more context than the window can hold.
Guides agents to write large tool outputs, plans, sub-agent findings, terminal logs, and learned preferences to files; discover and retrieve content with directory listing, glob, grep, and range-based reads; return compact summaries with file references instead of full outputs; and apply structured formats, per-agent isolation, existence checks, retention policies, and validation. The document includes Python-style pseudocode and YAML, JSONL, Markdown, and directory-layout examples.
- An engineer building a long-running agent needs plans and intermediate state to survive context refreshes.
- A developer running searches, database queries, or terminal tasks needs to offload outputs exceeding roughly 2,000 tokens and retrieve specific sections later.
- A multi-agent team needs isolated workspace files for research findings and handoffs instead of lossy multi-hop messages.
- A maintainer of agent skills needs to load full instructions only when a task makes them relevant.
- An operator managing temporary logs and scratch files needs retention rules to prevent unbounded directory growth.
What are this skill's strengths and limitations?
- Provides concrete patterns for tool-output offloading, plan persistence, sub-agent file communication, dynamic skill loading, and terminal-log persistence.
- Includes structured examples, retrieval techniques, directory organization, and warnings about concurrency and cleanup.
- The selective-retrieval approach directly targets limited context windows in long-running agent workflows.
- The shown frontmatter contains only name and description and no platform-specific extension, supporting broad Agent Skills compatibility.
- The material is primarily instructional and uses Python-style pseudocode rather than a packaged implementation or test suite.
- It depends on host-provided filesystem and search/read capabilities; bare model APIs need an external caller to supply them.
- Shared files still require explicit handling for concurrent writes, stale paths, format drift, and scratch-file growth.
- The self-modification pattern is explicitly experimental and requires validation and periodic review.
How do you install this skill?
Copy the entire skills/filesystem-context directory into the host's Agent Skills directory rather than flattening SKILL.md. For example:
mkdir -p .codex/skills
cp -R skills/filesystem-context .codex/skills/
The README also documents equivalent .claude/skills/, .cursor/skills/, and .agents/skills/ locations. The repository can alternatively be added as a Claude Code marketplace or Open Plugins directory, but those approaches discover or install the broader collection.
How do you use this skill?
Use it when context needs to live outside the prompt, for example: "Write large tool output to a scratch file, return only a summary and path, and use grep plus range-based reads for later retrieval. Persist the current plan in a structured file."
The documented activation scenarios include oversized tool output, multi-turn work, shared state between agents, and selective log or terminal-output queries. The host must provide the actual filesystem and search/read operations; the document does not define a standalone executable installer.
How does this skill compare with similar options?
The README distinguishes context engineering from prompt engineering: prompt engineering focuses on crafting instructions, while this Skill manages the broader set of prompts, tool outputs, history, and retrieved information entering the model's context.