repo-map
Skill1 starsChanged 41 days agoMITView on GitHub
Builds and maintains a lightweight architecture map of the current repository (folder structure, entry points, key dependencies) so the assistant doesn't have to re-explore the whole codebase on every task. Use this skill when starting work in a repository that has no `.claude/MAP.md` yet, or when the map is stale. Consult an existing map first before manually exploring an unfamiliar repo.
14 other projects use a version of this.
Adopted by
Most recently taken up by
- chuckplayer/claude-agent-packtheir own version, first seen Nov 16, 2026
- 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
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
- chuckplayer/claude-agent-pack★ 8same 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
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 repository5 other files it gives its agents.
- llms.txtllms.txt
- code-verifierSkill
- context-saverSkill
- perf-verifierSkill
- prompt-clarifierSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
If absent, survey the repo: top-level folders, README, package manifest, existing docs.
- Very specific: line 20
Write the map using the template below to .claude/MAP.md, recording the current git commit hash.
- Distinctive: line 21
If MAP.md exists, run the staleness check below.
- Distinctive: line 30
Update the recorded commit hash after any edit, incremental or full.
“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
Why this matters
Exploring a repo's structure from scratch on every task burns tool calls and tokens re-discovering things that don't change between tasks — which folder holds what, where the entry points are, how modules depend on each other. A cached map turns repeated exploration into a single read.
When to use
- No
.claude/MAP.mdexists yet in the repo root - MAP.md exists but a structural change has landed since it was last updated (see staleness check below)
- Starting a non-trivial task in an unfamiliar repo — check for a map before manually exploring
Process
- Check for
.claude/MAP.md. - If absent, survey the repo: top-level folders, README, package manifest, existing docs. Identify entry points (main/index files, app bootstrap, primary routes). Note the purpose of each top-level folder in one line. Note key dependencies between major modules (what calls what, not a full graph).
- Write the map using the template below to
.claude/MAP.md, recording the current git commit hash. - If MAP.md exists, run the staleness check below. If it says stale, apply the smallest edit that fixes it — don't rewrite the whole file unless told to do a full rebuild.
- On any task, read MAP.md first instead of re-exploring; only dig into files the map points at that are directly relevant to the task.
Staleness check
A raw "did the commit hash change" check is too eager — nearly every session adds some commit, and re-surveying the repo on every trivial change burns exactly the tokens this skill exists to save. Check structure, not commits:
- List what actually changed since the map's recorded commit, ignoring the map itself:
git diff --name-only <recorded-hash> HEAD -- . ':!.claude/MAP.md'. (No git history available? Compare the current folder listing against the Structure section instead.) - The map is stale only if a changed path introduces or removes a folder at the level the Structure section lists (e.g. a new
src/<name>/when the map listssrc/routes/,src/services/) that isn't already named there, or touches a file already listed as an entry point. A change confined to files inside a folder the map already describes doesn't make the map wrong — it's still accurate at the level the map operates on, so treat it as fresh and do nothing. - When it is stale, edit just the affected bullet(s) — add or remove the one line for the new/removed folder, or re-check the one entry point that changed. Reserve a full rebuild for when several top-level folders have shifted at once or the file no longer reflects the repo at a glance.
- Update the recorded commit hash after any edit, incremental or full.
Keep the map small
The map only pays off if reading it costs far less than exploring. Keep it under about 40 lines: one line per folder, no per-file listings, no restating the README. If it grows past that, cut detail instead of adding sections.
Template
# Repo Map
Last updated: <date>, commit <hash>
## Structure
- `src/` — ...
- `tests/` — ...
## Entry points
- `src/index.js` — app bootstrap
## Key dependencies
- `routes/` call into `services/`, which call `db/`Examples
Example 1 — no map yet
Repo has no .claude/MAP.md. Survey it, write the map fresh with the current commit hash.
Example 2 — trivial change, map stays fresh
Since the map's recorded commit, the only change is a new function added inside src/services/orderService.js — a file already covered by the src/services/ bullet. No new folder at the listed level, no entry-point file touched. The map is still accurate; do nothing.
Example 3 — structural change, incremental update
Since the map's recorded commit, a new src/jobs/ folder appeared with a scheduled-job file. The map lists src/routes/, src/services/, src/db/, so this is a new folder at the listed level, and it isn't in the map. Add one bullet — `src/jobs/` — scheduled background jobs — under Structure, update the recorded commit hash, and leave the rest of the file untouched.
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.

