Contexory Repo onboarding map
The question behind "what is this codebase" is almost never "describe every directory". It is: where does execution start, how do I run it, which parts are alive, and what do I need to know before I touch anything.
A generated tour that walks the directory tree answers none of those. This one is ordered by what a newcomer needs first.
Procedure
1. Get the mechanical map
<skill-dir> is the directory this SKILL.md was loaded from — the skill installs outside
your project, so its script is named by full path, never relatively.
python3 <skill-dir>/scripts/repo_map.py # whole repo
python3 <skill-dir>/scripts/repo_map.py --top 25 # widen the hot-files list
The script detects the stack from its manifests, lists workspace packages, extracts the declared run/test/build commands, finds entry points, ranks files by commit count, and locates docs and agent-instruction files. It reports what it found, not what it expected to find — a missing test command is reported as missing rather than guessed.
2. Read the instruction files first, if there are any
AGENTS.md, CLAUDE.md, CONTRIBUTING.md, .cursorrules. These are the highest-value
files in an unfamiliar repository and newcomers routinely miss them: they encode the
conventions that are not derivable from the code, and they are usually the only written
record of why the layout is what it is. Read them before forming any opinion about the
structure.
3. Follow the hot files, not the big ones
The commit ranking is the fastest route to where the work actually happens. A large file that has not changed in a year is settled; a medium file with sixty commits is the one you will be editing. Read the top five before anything else.
4. Verify the run and test commands rather than repeating them
The commands in package.json or the README are claims. Where it is safe and cheap, check
that the entry points they reference exist. Do not run install, build, migration or
deploy commands to find out — say which commands you verified structurally and which you
took on trust.
5. Name what you could not work out
An honest map has holes in it, and stating them is more useful than a smooth account that quietly guesses. If you could not tell how configuration is loaded, or which of three apps is the real entry point, that is the most useful sentence in the report — it is the first question the newcomer should ask a human.
Output
Keep it to one screen where possible:
- What this is — one sentence, from the manifests and instruction files
- Layout — the handful of directories that matter, not the whole tree
- Run it — install, dev, test, build, with a note on which were verified
- Where the work happens — the top churned files, with one line each
- Conventions to know — from the instruction files, the ones that would trip a newcomer
- Open questions — what you could not determine
What this skill deliberately does not do
- It does not write documentation into the repository. It produces a map for a reader;
committing an onboarding doc is a separate decision, and an unrequested
ONBOARDING.mdis noise in someone else's project. - It does not run install, build, migration or deploy commands. Onboarding is exactly the moment when the blast radius of a stray command is least understood.
- It does not describe every directory. Completeness here is the enemy — a tour of forty folders is what the file tree already gives you for free.
- It does not trust the README over the code. Where they disagree, it reports both and says which is which.
- It does not invent architecture. If the layering is unclear, that goes in open questions rather than into a confident paragraph.
When this is the wrong tool
- The README's claims are what you care about. Checking them against the code is verification, not orientation, and it wants a claim-by-claim pass rather than a map.
- You are about to change something and want to know what depends on it. That is a call-site question about one symbol, not a survey of the repository.
- You want to know what is untested. That is a coverage question.