Context Map
Agent-facing project documentation in two linked layers — so an AI coding agent never gets lost in a big codebase, and never forgets what was already decided.
A Claude Code skill / plugin that generates, decomposes, audits, reconciles, and conflict-checks the docs an AI agent actually needs. It is not a README, PRD, or architecture spec — it is navigation and memory built for LLM ingestion.
your-project/
├── agent-docs/ ← navigation (COMMITTED) "where do I go, what reads what"
│ ├── MAP.md router
│ ├── domains/*.md per-domain deep docs
│ └── _meta/*.json machine-readable links + freshness
└── context-map-<slug>/ ← memory (GITIGNORED) "what was decided, what's broken, what not to repeat"
├── context-map.md router + frontmatter
├── decisions.md D-### locked decisions
├── known-issues.md KI-### open issues + regression rules
├── gotchas.md G-### traps
└── tasks.md T-### next work
Why two layers
A single docs file fails an agent in two different ways, so the skill keeps two trees with opposite git policies:
| Navigation — agent-docs/ | Memory — context-map-<slug>/ |
|---|
| Git | committed — shared, reviewable | gitignored — private, .env-like |
| Answers | "where do I go, what reads what" | "what was decided, what's broken, what must I not repeat" |
| A fact goes here if… | it's code structure — domains, entry points, file routing, neighbors | it's project history / operational truth — decisions, known issues, gotchas, tasks |
| Stays fresh via | a CI freshness gate (fails the build when code changes but its domain doc doesn't) | a SessionStart staleness notice + manual update |
The two trees are cross-linked: MAP.md points at the memory router, the memory router points back at MAP.md, and _meta/links.json records the machine-readable pairing. Domain docs cite memory IDs (D-002, KI-001) instead of restating them, so there is one source of truth.
Why gitignore the memory? decisions.md / known-issues.md are operational notes that may name internal hosts, workarounds, and "do not ship this" caveats. They are treated like .env — useful to every future agent on your machine, never pushed to a public remote.
Install
The skill ships through the kyzdes/claude-skills marketplace:
/plugin marketplace add kyzdes/claude-skills
/plugin install context-map@claude-skills
Then just describe what you want in plain language — the skill triggers on intent, not on a command:
"Set up a context map for this repo so future sessions remember our decisions and stop re-litigating them."
"This monorepo is too big — my agent keeps loading the wrong files. Split it into per-domain docs and add a check that keeps them fresh."
Works in Claude Code, and the generated docs are wired into CLAUDE.md, AGENTS.md, GEMINI.md, or .cursor/rules/ so Cursor and Gemini CLI sessions read them first too.
What it does
Generation scales to the project. The skill runs an inspector (scripts/inspect_project.py) to size the repo (XS → XL) from source count, churn, and structure, then:
- XS–S — a lightweight memory tree only.
- M+ — the full memory tree plus the committed
agent-docs/ navigation layer (6–12 domains at M, 10–25 at L/XL). At ≥5 domains it dispatches one writer subagent per domain in parallel.
- Cross-checks code against existing docs to build a confidence ledger (
verified / inferred / stale / conflicting), so it never silently launders a guess into a fact.
- Verifies its own output — picks two questions an agent would really ask ("how does auth work end to end?", "where do I add an API route?"), starts from
MAP.md, and follows the trail. If it reads more than three files without an answer, that's a documented gap to fix before finishing.
Modes
You rarely name a mode — the skill infers it — but they're explicit when you want them:
