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---6
7# Agent Context System
8
9Agents 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.
10
11## The Two-File System
12
13- **`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.
15
16## Workflow
17
18### 1. Initialize
19
20Run `./scripts/init-agent-context.sh` to create `.agents.local.md` from template, ensure it's gitignored, and wire up agent tool configs.
21
22### 2. Work
23
24Read both files at session start. `AGENTS.md` gives compressed project knowledge. `.agents.local.md` gives accumulated learnings from past sessions.
25
26### 3. Grow
27
28At session end, append to the scratchpad's Session Log: what changed, what worked, what didn't, decisions made, patterns learned.
29
30### 4. Compress
31
32When the scratchpad hits 300 lines, compress: deduplicate, merge related entries, keep it tight.
33
34### 5. Promote
35
36During 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`.
37
38## Get Started
39
40When a user asks about setting up agent context:
41
421. **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.
43
442. **Check if `.agents.local.md` exists.** If not, run `./scripts/init-agent-context.sh` to set it up from template.
45
463. **Check if `.agents.local.md` is gitignored.** If not, add `.agents.local.md` to `.gitignore`.
47
484. **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).
49
50## Key Resources
51
52- **Full knowledge base:** `../SKILL.md` (root level) — comprehensive guide with research foundation
53- **Project template:** `../AGENTS.md` — the committed file structure and format
54- **Scripts:** `../scripts/` — init, compress, promote, validate, publish
55- **Deep docs:** `../agent_docs/` — conventions, architecture, gotchas (load on demand)
56
57## Important Context
58
59- **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.
63
64## Session Protocol
65
661. Read `AGENTS.md` and `.agents.local.md` (if it exists) before starting any task
672. Follow project conventions and boundaries defined in compressed format
683. **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 promotion
75
76> **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.
johnalbertini14-glitch