Context Management Skill

Design and operate agent context so it is fast, cheap, stable, and robust over long tool-using loops. Use a two-layer model:

1. •Global context (stable, cross-project, rarely edited; e.g. ~/.codex/)
2. •Local context (project-specific, frequently updated; lives in repo)

Workflow

1. •

   Separate global vs local context

   • •Global: invariant rules, assembly templates, stable checklists.
   • •Local: project goals, current state, logs, errors, and per-run artifacts.
   • •Prefer read-only access to global context during runs; update it only by explicit request.
   • •Ensure project .gitignore includes .cache/ (keep .cache/.gitkeep if you want the directory tracked).
2. •

   Define the invariant prefix

   • •Keep system/developer prompt prefixes stable across turns and sessions.
   • •Avoid timestamps, run IDs, random salts, or non-deterministic serialization in the prefix.
   • •Keep tool definitions stable; avoid dynamic add/remove mid-episode.
3. •

   Make context append-only

   • •Never rewrite or "clean up" earlier actions/observations; only append corrections.
   • •Ensure deterministic ordering for any serialized data you add to context (stable key order, stable formatting).
4. •

   Constrain actions without editing tool definitions

   • •Prefer masking/forcing at decode time if you own the runtime.
   • •If you only control prompts, keep tool definitions unchanged and append an Allowed actions block near the end of the context to gate behavior.
   • •Group tool names with consistent prefixes (e.g., browser_*, shell_*) so you can constrain by group.
5. •

   Use the filesystem as external memory

   • •Store large observations (pages, logs, diffs, stack traces, CSVs) in files, not in the prompt.
   • •Keep context compression reversible: retain pointers (file paths, URLs, IDs) so content can be reloaded on demand.
   • •Put only a short summary + pointer in the model context.
   • •Prefer per-run directories to avoid file contention (e.g. .cache/context/run/YYYYMMDD-HHMM/).
6. •

   Recite goals to control attention

   • •Maintain a todo.md (or equivalent) and rewrite it as the task progresses.
   • •Re-state the current objective and "next action" near the end of the context before each decision step.
7. •

   Preserve errors

   • •Keep failed attempts and error outputs visible in context (or in files referenced from context).
   • •Add a short postmortem note: "what failed / why / what to try next".
8. •

   Avoid few-shot pattern lock-in

   • •Do not let the context become a long chain of near-identical action/observation pairs.
   • •Introduce controlled variation in formatting/wording/order in the late (non-cached) part of context to break brittle imitation, while keeping the prefix stable.
9. •

   Concurrency safety

   • •Use a single-writer rule for local context files.
   • •Use a lock file (e.g. .cache/context/.lock) when writing shared local files.
   • •Prefer append-only logs and run-scoped subdirectories to avoid merge conflicts.

Deliverables

• •A compact "context contract" describing what is stable vs dynamic.
• •A filesystem memory layout (folders + key files) that the agent reads/writes.
• •A prompt assembly template for each agent step (decision, tool-call, user-response).

References

• •Templates: context-management/references/templates.md
• •Context contract: context-management/references/context_contract.md
• •Errors template: context-management/references/errors.md
• •Checklists: context-management/references/checklists.md