Help us improve
Share bugs, ideas, or general feedback.
From claudekit
Produces evidence-cited maps of unfamiliar codebase areas with file:line references for every claim. Use before non-trivial changes, onboarding, or multi-module refactors.
npx claudepluginhub duthaho/claudekit --plugin claudekitHow this skill is triggered — by the user, by Claude, or both
Slash command
/claudekit:map-codebaseThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A methodical exploration workflow that produces an evidence-cited map of a codebase
Produces a one-screen codebase map showing entry points, core modules, data flow, callers, and hidden coupling. Use when orienting in unfamiliar code.
Orchestrates parallel subagents to map any codebase, creating docs/CODEBASE_MAP.md with architecture, file roles, dependencies, and navigation. Updates incrementally via git or scans.
Persists codebase knowledge across sessions to avoid re-discovery. Use after exploration to record, before tasks to consult, or when dispatching subagents with module-specific context.
Share bugs, ideas, or general feedback.
A methodical exploration workflow that produces an evidence-cited map of a codebase area. Replaces ad-hoc grep with a disciplined four-step pass: scope, list, read, diagram. The output is a short artifact you can attach to a plan or design doc — file paths, line numbers, call directions, and the questions you couldn't answer from reading. The skill's value is enforcing that every claim about the code is backed by a specific file:line citation, not a memory or pattern-match. Senior ICs and tech leads use it to bound the blast radius of a change before they propose it.
Grep answers in 5 secondsGoal: Pin down what you are mapping and what you explicitly are not.
Inputs: A task, plan, or question that triggered the need to explore.
Actions:
I am mapping <X> in order to <Y>. X is concrete (a feature,
a module, a request path). Y is the decision the map will support.I am not mapping <Z>.
This prevents the exploration from sprawling.Output: A two-sentence scope statement at the top of your scratch artifact.
Goal: Enumerate every place execution can enter the area being mapped.
Inputs: The scope statement.
Actions:
Grep for the framework's routing
primitives.<file:line> — <what triggers it>.Output: A bullet list of entry points with file:line citations.
Goal: Read the actual code at each entry point and the immediate calls outward, collecting facts.
Inputs: The entry-points list.
Actions:
Output: A flat list of facts, each in form <file:line> — <what this code does>,
plus a short list of open questions.
Goal: Compress the trace into a single artifact a teammate can read in 3 minutes.
Inputs: The trace from Step 3.
Actions:
<file:line> — <what surprised me>)<question> — <where you'd need to look>)/tmp. The artifact is the deliverable.Output: A Markdown artifact at a known path. Maximum 300 lines.
| Excuse | Why it sounds reasonable | Why it's wrong | What to do instead |
|---|---|---|---|
| "I already know how this works." | You may have read this code before. Re-reading feels like wasted time. | Memory drift is real and unsensed. The function you remember was three commits ago; the current version has a different signature, a new branch, or a defensive check that changes behavior. The bugs that hit hardest in unfamiliar areas are usually in the code the engineer was sure they knew. | Read the file at the actual current commit before you cite it. If your memory matches what's there, the read takes 60 seconds. If it doesn't, you just avoided a confident wrong answer in your plan. |
| "Grep is enough — I don't need to read the function." | Grep does locate code. For a one-line lookup, that's the whole job. | Grep tells you where something appears, not what it does. A function that grep matches on cache.get may also delete on cache miss, may wrap a remote call, may log to a different sink. Citing the file:line without reading it is asserting behavior you haven't verified. | After Grep finds the call site, open the file and read the function body. Cite file:line in your map only after reading. |
| "Two levels deep is enough — I don't need to follow further." | Going arbitrarily deep is how exploration sprawls. Time-boxing is correct. | The trap is stopping deep enough to feel productive but not deep enough to answer the actual scope question. If your scope was "what does this endpoint do," and the second level is a generic ORM call, the answer is still incomplete. | Re-read your Step 1 scope sentence. If your current trace doesn't answer the in order to <Y> clause, you haven't gone deep enough on the calls that matter. Don't go deeper on calls that don't. |
| "I'll write it up later — let me just keep exploring." | Writing while exploring breaks flow. | "Later" usually means after the next task arrives, by which point the trace is gone from working memory. The map ends up reconstructed from a fuzzy recollection, with citations the engineer "thinks are right." That's the same failure mode as not mapping at all. | Open the artifact file at Step 1 and append as you trace. The artifact is grown, not written at the end. If you finish the trace and the artifact is empty, you're going to write it from memory, badly. |
| "ASCII diagrams are silly — text is fine." | Some maps genuinely don't need a diagram. Pure prose can carry. | A diagram-free writeup of a multi-entry-point system is hard to scan and hard to verify. The reader has to mentally reconstruct the call graph from prose. They won't. They'll skim, miss something, and your map becomes a thing nobody actually used. | If there are 3+ entry points or 2+ modules in the scope, draw the call graph. ASCII is fine. Half the value of mapping is the picture in someone else's head, not the prose in yours. |
| Checkpoint | Required artifact | What "no evidence" looks like |
|---|---|---|
| End of Step 1 | Two-sentence scope statement at top of artifact | "I'm exploring the auth module." |
| End of Step 2 | Bulleted entry-points list with file:line on every row | "There are a bunch of routes that hit this." |
| End of Step 3 | Flat trace with file:line on every fact | "It looks like the cache is checked first, then the DB." |
| End of Step 4 | Markdown artifact saved at a known path with all 5 sections, ≤300 lines | "I have a good mental model now." |
If the artifact does not exist as a file you could send to a teammate, you have not mapped the codebase. You have read some code.