context-window-stewardship

name	context-window-stewardship
description	Use when context window is filling up, when agent responses degrade in quality over a long session, when deciding what to load into an agent's context vs keep in files, or when designing multi-agent systems where subagents need isolated contexts. Triggers on: context full, context rot, compaction, session degradation, token limit.
tier	FULL
tags	["context","tokens","compaction","progressive-disclosure","memory","subagents","apex-os"]
source	DeepLearning.AI Agent Skills course + HandsOnLLM
last-updated	"2026-02-27T00:00:00.000Z"

Context Window Stewardship — APEX OS Standard

Overview

Context window = a public good. Every token added degrades the space available for reasoning. The goal is maximum signal per token. Context rot is real.

The 3-Stage Loading Hierarchy (APEX OS Standard)

┌─────────────────────────────────────────────────────────────────────────┐
│ Stage 1 — Always in context (name + description only)                   │
│ → Agent uses this to decide WHETHER to load the skill                   │
│ → Hard limit: 2 lines. Never exceed.                                    │
├─────────────────────────────────────────────────────────────────────────┤
│ Stage 2 — Loaded on trigger (full SKILL.md body)                        │
│ → Loaded when skill description semantically matches the task           │
│ → Hard limit: 500 lines                                                 │
│ → Overflow → move to references/                                        │
├─────────────────────────────────────────────────────────────────────────┤
│ Stage 3 — Loaded on demand (references/, scripts/, assets/)             │
│ → Only when workflow explicitly needs them                              │
│ → Never inline large lookup tables or templates in SKILL.md            │
└─────────────────────────────────────────────────────────────────────────┘

What Belongs Where

┌──────────────────────────────────┬──────────────────────────────────────┐
│ Content                          │ Location                             │
├──────────────────────────────────┼──────────────────────────────────────┤
│ Skill name + trigger description │ SKILL.md frontmatter (Stage 1)       │
│ Core workflow steps (≤500 lines) │ SKILL.md body (Stage 2)              │
│ Lookup tables > 20 rows          │ references/lookup.md (Stage 3)       │
│ Output format templates          │ assets/template.md (Stage 3)         │
│ Executable scripts               │ scripts/run.sh (Stage 3)             │
│ Session logs / project artifacts │ NOT IN SKILLS — wrong place          │
│ Personal documents               │ NOT IN SKILLS — wrong place          │
│ Large reference docs (>500 lines)│ NOT IN SKILLS — use RAG instead      │
└──────────────────────────────────┴──────────────────────────────────────┘

Subagent Exception (CRITICAL)

┌─────────────────────────────────────────────────────────────────────────┐
│ Main agent:  Progressive disclosure applies.                            │
│              name+desc → SKILL.md → references on demand               │
│                                                                         │
│ ⚠️  Subagent:  ENTIRE SKILL.md is pre-loaded at dispatch.              │
│              No progressive disclosure. No on-demand loading.           │
│              Subagents do NOT inherit parent skills.                    │
│              Skills must be explicitly assigned to each subagent.       │
└─────────────────────────────────────────────────────────────────────────┘

GSD's Solution to Context Rot

GSD (get-shit-done, gsd-build/get-shit-done) solves context rot by running each plan in a fresh 200k context subagent. The orchestrator stays lean.

┌──────────────────────────────────────────────────────────────────────┐
│ Pattern: Orchestrator stays lean, workers get fresh context          │
│                                                                      │
│  Main session (30-40% context)                                       │
│         │                                                            │
│         ├──→ Subagent A (200k fresh) → executes Plan 1 → commits   │
│         ├──→ Subagent B (200k fresh) → executes Plan 2 → commits   │
│         └──→ Subagent C (200k fresh) → executes Plan 3 → commits   │
│                                                                      │
│  Result: No context rot. Quality stays high across 10+ plans.       │
└──────────────────────────────────────────────────────────────────────┘

Context Budget Guidelines

┌──────────────────────────────┬──────────────────────────────────────┐
│ Item                         │ Target budget                        │
├──────────────────────────────┼──────────────────────────────────────┤
│ System prompt                │ < 2,000 tokens                       │
│ Skills loaded (per session)  │ < 5,000 tokens total                 │
│ Working memory               │ < 20% of context window              │
│ Single SKILL.md file         │ < 500 lines (~3,000 tokens)          │
│ Subagent task prompt         │ < 1,000 tokens                       │
└──────────────────────────────┴──────────────────────────────────────┘

Session Compaction Signs (time to compact or hand off)

• Agent starts repeating itself or forgetting recent instructions
• Response quality degrades noticeably mid-session
• Agent references stale information from much earlier in session
• Context shows > 70% utilisation

Common Mistakes

• Loading all skills at session start — kills context budget immediately
• Putting large lookup tables in SKILL.md body — move to references/
• Not assigning skills explicitly to subagents (they don't inherit)
• Fighting context rot by repeating instructions — spawn fresh subagent instead