repo-map
Skill8 starsChanged 35 days agoMITView on GitHub
Generate or refresh a durable, directory-level map of the codebase — what each directory is for and its key entry-point files — stored as memory/architecture/repo-map.md and stamped with the git commit it was verified against. Use to create the map, refresh it after the tree drifts, or check whether it is stale. Trigger this when someone says: map the repo, build a repo map, what does each directory do, refresh the repo map, is the repo map stale, generate the file manifest, update the codebase map. Do NOT use to produce a full onboarding orientation — use /onboard instead (it reads this map). Do NOT use to search memory — use /memory-query instead.
14 other projects use a version of this.
Adopted by
Most recently taken up by
- ychampion/ystacktheir own version, first seen Nov 15, 2026
- ejboy/agent-scriptstheir own version, first seen Nov 13, 2026
- jocarrd/crux-agentstheir own version, first seen Nov 8, 2026
- idaibin/skillstheir own version, first seen Nov 8, 2026
- Tcuzzo/backs-aios-skillstheir own version, first seen Nov 3, 2026
- marinvch/Cortextheir own version, first seen Nov 1, 2026
Other versions14 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 14
- AnastasiyaW/claude-code-config★ 214same name
- AnastasiyaW/codex-claude-code-config★ 214same name
- ejboy/agent-scripts★ 118same name
- idaibin/skills★ 6same name
- yeaight7/agent-powerups★ 6same name
- jocarrd/crux-agents★ 4same name
- ychampion/ystack★ 4same name
- mmaripanguec/dev-sdd-kit★ 2same name
- Tcuzzo/backs-aios-skills★ 2same name
- David-Florian2013/Stop-trusting-made-it-faster-here-is-5-best-skills-for-Claude-★ 1same name
4 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- backlogSkill
- conventionsSkill
- debugSkill
- devops-azureSkill
- devops-githubSkill
- devopsSkill
- hotfixSkill
- implementSkill
- interview-meSkill
- lint-agentsSkill
- memory-auditSkill
- memory-querySkill
- obsidian-briefSkill
- obsidian-captureSkill
- obsidian-dailySkill
- obsidian-recapSkill
- obsidian-searchSkill
- obsidianSkill
- onboardSkill
- pack-reviewSkill
- planSkill
- refactorSkill
- review-prSkill
- scaffoldSkill
- setup-projectSkill
- smellSkill
- spec-intakeSkill
- system-checkSkill
- whatSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 1 is distinctive, and 6 are very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
If memory/ does not exist in this project, report that and suggest /setup-project — do not create it here.
- Very specific: line 23
Write memory/architecture/repo-map.md using the format below, stamping verified-at-commit with the HEAD from step 1.
- Very specific: line 27
Read the map's verified-at-commit value.
- Distinctive: line 30
Add new directories, remove entries for directories that no longer exist.
- Very specific: line 41
Follow docs/MEMORY-WRITING.md.
- Very specific: line 63
Unreachable stamp: If verified-at-commit is not an ancestor of HEAD (history was rewritten), you cannot compute a meaningful diff — …
- Very specific: line 65
Obsidian sync is automatic: Do not write to the vault directly.
“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repo Map
Maintain a durable, cross-session map of the codebase at directory/module granularity — one entry per meaningful directory, with only its 1–3 entry-point files called out by name. The map lives at memory/architecture/repo-map.md, so it is read by every agent via the memory rule and auto-synced to Obsidian by the memory-snapshot hook.
The map is stamped with the git commit it was last verified against (verified-at-commit). That stamp is what makes it resilient: staleness is a git diff question, not a guess, and refreshes re-describe only the directories that actually changed.
If memory/ does not exist in this project, report that and suggest /setup-project — do not create it here.
Modes
Pick the mode from context. Default to refresh when the file already exists, generate when it does not.
generate — no map exists yet
git rev-parse --short HEADto capture the current commit.- Glob the tree (respecting
.gitignore) to enumerate meaningful directories. Skip vendored/build/output dirs (node_modules,bin,obj,dist,.git,target,venv). - For each directory, determine its purpose from the files it contains and name the 1–3 files a newcomer would open first (entry points, orchestrators, config roots).
- Write
memory/architecture/repo-map.mdusing the format below, stampingverified-at-commitwith the HEAD from step 1.
refresh — map exists (default)
- Read the map's
verified-at-commitvalue. git diff --name-only <verified-at-commit>..HEAD -- . ':(exclude)memory/architecture/repo-map.md'to find changed paths. Always exclude the map's own file — a prior stamp bump is not codebase drift. If the stamped commit is unreachable (rebased/squashed), fall back to a full regenerate and note it.- Re-describe only the directories that contain changed, added, or deleted files. Leave untouched directories exactly as they are — do not rewrite the whole file.
- Add new directories, remove entries for directories that no longer exist.
- Re-stamp
verified-at-commitwith the current HEAD and updatelast-updated.
verify — report staleness only, no writes
- Read
verified-at-commit. git diff --name-only <verified-at-commit>..HEAD -- . ':(exclude)memory/architecture/repo-map.md'and list which mapped directories have drifted. Excluding the map's own file keeps a prior stamp bump from reading as drift.- Report: up to date, or "N directories drifted since
<sha>— run/repo-map refresh." Make no edits.
File format
Follow docs/MEMORY-WRITING.md. Fenced lowercase YAML — the seven required keys plus two extra fields, last-updated and verified-at-commit:
---
date: YYYY-MM-DD
type: pattern
status: active
superseded-by: n/a
scope: global
overrides-convention: no
related-to: n/a
last-updated: YYYY-MM-DD
verified-at-commit: <short-sha>
---Body: one ## <dir>/ heading per meaningful directory, a one-line purpose, then a short bullet list of only the entry-point files that matter. Directory-level is the rule; do not write one line per source file.
Gotchas
- Per-file creep: The value is low upkeep. If you find yourself listing every file in a directory, stop — name only the entry points. A per-file manifest rots the moment a file moves and defeats the purpose.
- Full rewrite on refresh: refresh must be surgical. Re-describing untouched directories wastes tokens and risks drift in stable entries. Only touch directories that appear in the
git diff. - Unreachable stamp: If
verified-at-commitis not an ancestor of HEAD (history was rewritten), you cannot compute a meaningful diff — regenerate fully and note why in your report. - This is not onboarding: The map is a structural index, not a narrative. Purpose, architecture explanation, and first-tasks belong in
/onboard, which consumes this map. Keep the map terse. - Obsidian sync is automatic: Do not write to the vault directly.
memory/architecture/repo-map.mdis copied to the vault by the memory-snapshot hook on SessionEnd — no extra step needed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

