# Map > Codebase orientation for an unfamiliar or large repo — "map this before I work in it." Fans out read-only Explore sub-agents that navigate the code (keyless — grep/glob/read, no embeddings to go stale) along the order that matters: entry points, build/test/lint commands, architecture and key abstractions, conventions and gotchas, test layout. Distills the findings into a lean AGENTS.md at the repo root — the cross-tool standard file many agents auto-load — where every claim points to a real file and nothing survives that isn't load-bearing. Human-in-the-loop: it drafts, you approve, and it never writes or commits into your repo without an explicit yes. Stamps the map with date + commit so /map refresh regenerates only what went stale. Use before working in a repo you or the agent don't know — e.g. "/map", "/map the auth subsystem", "generate an AGENTS.md", "/map refresh". Run it upstream of feature or bugfix; for the end-of-session shipping gate use done. - Skill: `duthaho/map` (Agent Skill) - Install (CLI): `npx skillmds@latest add duthaho/map` - Raw SKILL.md: https://api.skillmd.com/api/skills/duthaho/map/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: duthaho (https://skillmd.com/u/duthaho) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/duthaho/map --- # map — orient the agent to an unfamiliar codebase `/map` — map the whole repo into a lean AGENTS.md at its root `/map ` — deep-map one area, into a scoped section `/map refresh` — re-check an existing map and update only what went stale Answer one question: **what would a competent engineer need to know before touching this repo — and nothing more?** The strongest lever in agentic coding isn't a smarter model, it's better orientation: an agent that knows the entry points, the build commands, and the load-bearing conventions makes the right change; one that guesses edits the wrong layer. ## Step 0 — Scope, and respect what exists First, look before generating: - **Existing agent files?** Check for `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`. If one exists, this is a **REFRESH**, not a fresh write — read it, and update in place rather than duplicating. If a `CLAUDE.md` already carries the knowledge, offer to have `AGENTS.md` `@import` it instead of restating it. If the existing map carries a stamp and HEAD has moved past it, state the drift in one line when naming the mode — "map is N commits behind (touched: X, Y)" via `git rev-list --count` + `git diff --stat` over `..HEAD` — and offer the refresh unless this run already is one. A stamp that no longer resolves (rebase, shallow clone) is itself the staleness signal: report it and offer a fresh map. Staleness surfaces at every touch, never only when someone remembers `/map refresh`. - **Size the repo** (`git ls-files | wc -l`, top-level layout) to scale the fan-out: a small repo maps in one pass inline; a large or polyglot one gets the full parallel sweep below. - **A subsystem argument** (`/map the payment flow`) narrows every step to that area and produces a scoped section, not a whole-repo rewrite. State which mode you picked (NEW / REFRESH / FOCUS) and why. ## Step 1 — Fan out along the read-first order Dispatch read-only **Explore** sub-agents — one per lens — navigating by `grep`/`glob`/`read` and following imports (no embeddings, no pre-index; always fresh). This is the order practitioners converge on; run the lenses concurrently: 1. **Entry points & structure** — how does execution start (`main`, routes, CLI, handlers)? Top-level module/package layout and what each directory is *for*. 2. **Build / test / lint commands** — the knowledge no amount of code-reading reveals cheaply: the exact commands, from `package.json` scripts, `Makefile`, `pyproject.toml`, CI config. This is the single highest-value section. 3. **Architecture & key abstractions** — the main entities/types, the layers and their boundaries, how data flows through, the 3–5 files that matter most. 4. **Conventions & gotchas** — patterns the repo follows that deviate from the language default; footguns; "don't touch X"; implicit invariants a newcomer would break. 5. **Tests & fixtures** — how tests are organized, where fixtures/factories live, the command that runs a single test. **Lossless hand-off:** each sub-agent writes its full findings to `out/map/.work/.md` and returns a compact summary; you synthesize from the files, not the relay. **Every finding names a file path** — a landmark without a locator is a guess, and a guess in a map is worse than a blank. ## Step 2 — Distill to a LEAN AGENTS.md Now cut. A bloated agent file gets *ignored* — the failure this skill must not cause. For every candidate line apply the litmus test: **would removing it make the agent make a mistake?** If not, cut it. Keep: - What can't be guessed from reading code (commands, non-obvious conventions, gotchas, the "why" behind a structure). Drop: - Anything a `read` of the code trivially reveals, generic best-practices, restated language docs, and prose where a file path would do. Prefer signatures and paths over paragraphs. Target well under ~200 lines — shorter is stronger. Structure: ```markdown # AGENTS.md ## What this is ## Build, test, run ## Architecture ## Conventions & gotchas ## Landmarks ``` ## Step 3 — Approve, then write (never unprompted) This file lands in **the user's repo**, so nothing is written without a yes: 1. Show the full drafted `AGENTS.md` in chat and invite edits — cuts as much as additions. 2. On approval, write it to the repo root (or update the existing file), stamped with today's `date +%F` and the current commit sha. 3. **Offer, don't perform, the commit** — draft a message per the repo's convention, but committing and pushing wait for an explicit yes, same as every other skill here. 4. Note that `feature` and `bugfix` will now read this file at the start of their runs — the map pays off downstream. **Auto mode (under autopilot):** the draft→approve gate becomes write-and-log — the map is written and stamped, the run's `log.md` records what was generated and why, and committing still follows the run's charter. On **REFRESH**: diff the map's claims against the current tree — flag sections whose cited files moved, changed shape, or vanished; regenerate only those; re-stamp. Don't rewrite what's still true. Command-shaped claims are re-proven by running them, not by checking that the paths they mention still exist — a command that no longer runs as claimed is stale even when every cited file is in place; update the claim to what actually happened. Read-only commands (test, lint, validate) run directly; state-changing ones (install, deploy, migrate) only via an explicit dry-run flag — no dry-run mode means the claim is marked unverified, never executed. ## Guardrails - **A wrong map is worse than none.** A confident-but-stale line actively degrades the agent's reasoning. Every claim cites a file that exists; when unsure, leave it out and say so. - **Lean or it's ignored.** The litmus test is non-negotiable — cut ruthlessly. - **Never write or commit unprompted.** The output modifies the user's repo; draft → approve → write, and commit only on an explicit yes. (In auto mode, the autopilot charter is the prompt — the write is logged, not asked.) - **Navigate, don't index.** Keyless by design — grep/glob/read/LSP, no embeddings to leak or go stale. Re-derived-but-fresh beats cached-but-wrong. - **Evidence is a path.** No landmark, convention, or command without a locator or the command itself. The map is a set of verifiable pointers, not prose. - **Respect what's there.** An existing AGENTS.md/CLAUDE.md is updated, not bulldozed; manual edits by the user are preserved.