Agent Context System
Agents start from zero every session. This skill solves that with two markdown files: one committed (AGENTS.md), one gitignored (.agents.local.md). You read both at session start, update the scratchpad at session end, and promote stable patterns over time.
The Two-File System
AGENTS.md — Project source of truth. Committed and shared. Under 120 lines. Contains compressed project knowledge (patterns, boundaries, gotchas, commands, architecture)..agents.local.md — Personal scratchpad. Gitignored. Grows over time as you log what you learn each session. Session notes, dead ends, preferences, patterns waiting for promotion.
Workflow
1. Initialize
Run ./scripts/init-agent-context.sh to create .agents.local.md from template, ensure it's gitignored, and wire up agent tool configs.
2. Work
Read both files at session start. AGENTS.md gives compressed project knowledge. .agents.local.md gives accumulated learnings from past sessions.
3. Grow
At session end, append to the scratchpad's Session Log: what changed, what worked, what didn't, decisions made, patterns learned.
4. Compress
When the scratchpad hits 300 lines, compress: deduplicate, merge related entries, keep it tight.
5. Promote
During compression, if a pattern recurs across 3+ sessions, flag it in the scratchpad's "Ready to Promote" section. The human decides when to move it into AGENTS.md.
Get Started
When a user asks about setting up agent context:
Check if AGENTS.md exists. If not, they need to copy it from this template or create from scratch. Read the template at the root of this repo for reference.
Check if .agents.local.md exists. If not, run ./scripts/init-agent-context.sh to set it up from template.
Check if .agents.local.md is gitignored. If not, add .agents.local.md to .gitignore.
Ask which agents they use. The init script can wire up Claude Code (CLAUDE.md symlink), Cursor (.cursorrules), Windsurf (.windsurfrules), or Copilot (copilot-instructions.md).
Key Resources
- Full knowledge base:
../SKILL.md (root level) — comprehensive guide with research foundation
- Project template:
../AGENTS.md — the committed file structure and format
- Scripts:
../scripts/ — init, compress, promote, validate, publish
- Deep docs:
../agent_docs/ — conventions, architecture, gotchas (load on demand)
Important Context
- Instruction budget: Frontier LLMs follow ~150-200 instructions. Claude Code's system prompt uses ~50. Keep
AGENTS.md under 120 lines.
- Passive context wins: Vercel evals: 100% pass rate with embedded context vs 53% when agents decide to look things up.
- Subagent-ready: Subagents don't inherit conversation history. They only get the root instruction file. Tell them explicitly to read
.agents.local.md too.
- Compressed format: Use pipe-delimited patterns (
pattern | where-to-see-it), boundaries (rule | reason), gotchas (trap | fix). Dense beats verbose.
Session Protocol
- Read
AGENTS.md and .agents.local.md (if it exists) before starting any task
- Follow project conventions and boundaries defined in compressed format
- At session end, append to
.agents.local.md Session Log. This is the most commonly missed step. If the user appears to be ending the session without asking you to log, proactively offer to update the scratchpad.
- Done: (what changed)
- Worked: (reuse this)
- Didn't work: (avoid this)
- Decided: (choices and reasoning)
- Learned: (new patterns or gotchas)
- When scratchpad exceeds 300 lines, compress and flag recurring patterns (3+ sessions) for promotion
Known gap: Most agent tools (Copilot Chat, Cursor, Windsurf) end sessions silently — no hook fires. Session logging depends on the agent seeing Rule 7 in AGENTS.md and acting on it, or the user prompting "log this session." Claude Code's auto memory handles this automatically.
1---2name: agent-context-system-23description: Persistent local-only memory for AI coding agents. AGENTS.md (committed) + .agents.local.md (gitignored) = context that persists across sessions. Read both at start, update scratchpad at end, promote stable patterns over time.4license: See LICENSE file in repository root5---67# Agent Context System89Agents start from zero every session. This skill solves that with two markdown files: one committed (`AGENTS.md`), one gitignored (`.agents.local.md`). You read both at session start, update the scratchpad at session end, and promote stable patterns over time.1011## The Two-File System1213- **`AGENTS.md`** — Project source of truth. Committed and shared. Under 120 lines. Contains compressed project knowledge (patterns, boundaries, gotchas, commands, architecture).14- **`.agents.local.md`** — Personal scratchpad. Gitignored. Grows over time as you log what you learn each session. Session notes, dead ends, preferences, patterns waiting for promotion.1516## Workflow1718### 1. Initialize1920Run `./scripts/init-agent-context.sh` to create `.agents.local.md` from template, ensure it's gitignored, and wire up agent tool configs.2122### 2. Work2324Read both files at session start. `AGENTS.md` gives compressed project knowledge. `.agents.local.md` gives accumulated learnings from past sessions.2526### 3. Grow2728At session end, append to the scratchpad's Session Log: what changed, what worked, what didn't, decisions made, patterns learned.2930### 4. Compress3132When the scratchpad hits 300 lines, compress: deduplicate, merge related entries, keep it tight.3334### 5. Promote3536During compression, if a pattern recurs across 3+ sessions, flag it in the scratchpad's "Ready to Promote" section. The human decides when to move it into `AGENTS.md`.3738## Get Started3940When a user asks about setting up agent context:41421. **Check if `AGENTS.md` exists.** If not, they need to copy it from this template or create from scratch. Read the template at the root of this repo for reference.43442. **Check if `.agents.local.md` exists.** If not, run `./scripts/init-agent-context.sh` to set it up from template.45463. **Check if `.agents.local.md` is gitignored.** If not, add `.agents.local.md` to `.gitignore`.47484. **Ask which agents they use.** The init script can wire up Claude Code (CLAUDE.md symlink), Cursor (.cursorrules), Windsurf (.windsurfrules), or Copilot (copilot-instructions.md).4950## Key Resources5152- **Full knowledge base:** `../SKILL.md` (root level) — comprehensive guide with research foundation53- **Project template:** `../AGENTS.md` — the committed file structure and format54- **Scripts:** `../scripts/` — init, compress, promote, validate, publish55- **Deep docs:** `../agent_docs/` — conventions, architecture, gotchas (load on demand)5657## Important Context5859- **Instruction budget:** Frontier LLMs follow ~150-200 instructions. Claude Code's system prompt uses ~50. Keep `AGENTS.md` under 120 lines.60- **Passive context wins:** Vercel evals: 100% pass rate with embedded context vs 53% when agents decide to look things up.61- **Subagent-ready:** Subagents don't inherit conversation history. They only get the root instruction file. Tell them explicitly to read `.agents.local.md` too.62- **Compressed format:** Use pipe-delimited patterns (`pattern | where-to-see-it`), boundaries (`rule | reason`), gotchas (`trap | fix`). Dense beats verbose.6364## Session Protocol65661. Read `AGENTS.md` and `.agents.local.md` (if it exists) before starting any task672. Follow project conventions and boundaries defined in compressed format683. **At session end, append to `.agents.local.md` Session Log.** This is the most commonly missed step. If the user appears to be ending the session without asking you to log, proactively offer to update the scratchpad.69 - Done: (what changed)70 - Worked: (reuse this)71 - Didn't work: (avoid this)72 - Decided: (choices and reasoning)73 - Learned: (new patterns or gotchas)744. When scratchpad exceeds 300 lines, compress and flag recurring patterns (3+ sessions) for promotion7576> **Known gap:** Most agent tools (Copilot Chat, Cursor, Windsurf) end sessions silently — no hook fires. Session logging depends on the agent seeing Rule 7 in AGENTS.md and acting on it, or the user prompting "log this session." Claude Code's auto memory handles this automatically.
modbender