Context Window

Concept of the skill

A context window is finite working memory shared by instructions, tools, skills, conversation history, tool results, reasoning/output budget, and files.

Coverage

The quantitative discipline behind an agent's working memory. Allocates the context-window budget across three zones: System (system prompt, rules, tool schemas), Skill Injection (the SKILL.md files auto-loaded for the current task), and Working (conversation, tool results, file contents, agent output). Names the three context health states — ok (< 60% used), compact (60–80%), exhausted (> 80%) — and the 80% compaction rule that compaction must always trigger before the budget is fully consumed, leaving 20% as the safety margin for finishing the current operation, writing the checkpoint, running the closeout protocol, and emitting the continuation signal. Specifies the pre-compact protocol (commit uncommitted changes, write the continuation signal, update the checkpoint, save state that cannot be re-derived from git or disk) and the post-compact recovery flow (re-injection of git status, active-task reference, recent commits, critical findings). Catalogs typical token consumption per operation type (full file read 20–40K, large tool-result JSON 10–30K, single SKILL injection 3–8K, fixed system overhead) and the five token-reduction techniques: deterministic-CLI over heavy MCP / tool-result paths, targeted file reads with offset + limit instead of full-file reads, search-before-read (grep first, read the match), progressive skill disclosure (small SKILL.md kept always loaded; large reference files loaded on demand), and count-mode for exploration (count matches, then read the few that matter). Specifies the cross-session persistence hierarchy — git history > files on disk > durable memory > live context — and uses it to decide what to checkpoint before compaction. Lists per-model-class context strategies for 1M, 200K, and 128K windows.

Philosophy of the skill

The context window is the agent's working memory. Unlike human memory, it has a hard ceiling — when it fills, information is permanently lost from the live session unless it has been checkpointed somewhere durable. Managing the window is not optional. It is the difference between completing a long task and crashing mid-work with the most recent reasoning gone.

The trap of large windows is the assumption that they are effectively unlimited. A 1M-token window feels infinite until a single 2000-line file read consumes 30K, three of those plus a long tool-result chain pushes past 200K, and the agent is at 60% before any real implementation has happened. The ceiling is real, and it is closer than the headline number suggests. Discipline at 200K is identical to discipline at 1M; only the absolute numbers move.

The 80% rule exists because compaction is itself an operation that needs budget. Hitting 100% mid-operation loses the operation. Compacting at 80% preserves it — the remaining 20% pays for the act of preserving.

Source Notes

Current vendor docs agree on the central budget shape: the context window is a finite store for prior conversation and current-turn input, and output or thinking/tool-use behavior also competes for capacity in provider-specific ways. Anthropic's context-window docs describe conversation history accumulating across turns, 200K and 1M Claude classes, context awareness, tool-result and extended-thinking nuances, and server-side compaction / context editing options. Google's Gemini long-context guide frames long context as short-term memory, notes 1M+ token Gemini windows, and still recommends optimization techniques such as context caching for high-input workloads. OpenAI's model comparison docs expose model-specific context-window and max-output-token values, which is the operational reminder that planning must use the actual model selected at runtime, not a generic "frontier model" assumption.