codemap
/codemap
Trace one flow through a codebase and write it as a cited markdown map (Mermaid diagram plus stages with steps, reads and writes). Use when the user asks how a flow, feature or system works in a repo ("how does X work", "trace X", "map what happens when Y"), or wants a flow doc for onboarding, a PR review or AI-written code.
- Author
- capgoblin ↗
- Repository
- codemap ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/cite.py
What it does and when to use it
Trace one flow through a codebase and write it as a cited markdown map (Mermaid diagram plus stages with steps, reads and writes). Use when the user asks how a flow, feature or system works in a repo ("how does X work", "trace X", "map what happens when Y"), or wants a flow doc for onboarding, a PR review or AI-written code.
Triggers from the description
Original author description
Trace one flow through a codebase and write it as a cited markdown map (Mermaid diagram plus stages with steps, reads and writes). Use when the user asks how a flow, feature or system works in a repo ("how does X work", "trace X", "map what happens when Y"), or wants a flow doc for onboarding, a PR review or AI-written code.
How it works
- Rules
- Steps
- Choices already made
- Strict mode (only when the user asks)
- Not in scope
SKILL.md preview
---
name: codemap
description: Trace one flow through a codebase and write it as a cited markdown map (Mermaid diagram plus stages with steps, reads and writes). Use when the user asks how a flow, feature or system works in a repo ("how does X work", "trace X", "map what happens when Y"), or wants a flow doc for onboarding, a PR review or AI-written code.
---
# Codemap
Writes `docs/flows/<slug>.md`: a map of ONE flow in which every claim cites code. Read-only on the repo, except for that one file.
## Rules
1. **Cite only what a tool showed you in this session.** Copy `path:lines` from Read or `grep -n` output. Never write a line number from memory.
2. **A claim with no citation is not written.** The script rejects it.
3. **Do not drop a real hop on a hunch.** If you cannot prove a hop, keep it and mark it ⚠️ unsure.
4. **Stage level first.** 3 to 7 stages. Step over plumbing (auth, logging, retries, getters).
5. **Secrets stay out.** Never open `.env*`, keys, or git-ignored files. Never copy a secret value into the file.
6. **Be honest in the card.** Write `partial` and the reason if you stopped early or left hops unsure. Put doubts in the card's Doubts row.
## Steps
- [ ] **1. Scope.** Find 2 to 5 entry points with `grep` and the outline (routes, commands, handlers, jobs). Prefer the outermost handler. If the user did not name one, ask them to pick. Run `git rev-parse HEAD` and `git status --porcelain`.
- [ ] **2. Walk.** From the entry, follow the flow at stage level. For each hop note caller, callee, kind (`call`, `async`, `error`, `branch`) and the line that proves it. Stop at the end of the flow, at a third-party library, or after 40 hops (ask before going further).
- [ ] **3. Type each hop.** Direct: the callee's name is in the caller's lines (`grep -nw`). Anything else is indirect: a queue, a registry, a string dispatch, a callback. For an indirect hop, read the wiring yourself and follow it to where it is registered. Cite the wiring in the Evidence cell. If you cannot find the full chain, mark the hop ⚠️ unsure.
- [ ] **4. Shape it.** Cut the flow into 3 to 7 stages, with one level of steps inside each. Note each read and write with the line that does it.
- [ ] **5. Draft** the file from [TEMPLATE.md](TEMPLATE.md).
- [ ] **6. Run the check:** `python3 scripts/cite.py check <file>`. It is free. Fix every FAIL.
- [ ] **7. Tell the user** the path, the status, and the top doubts.
`scripts/` is in the folder that holds this SKILL.md.
## Choices already made
- Output: `docs/flows/<slug>.md`. Create the folder if needed.
- Links: GitHub permalinks with the commit sha when `git remote get-url origin` is a GitHub URL. Otherwise relative links.
- Depth: stages plus one level of steps.
## Strict mode (only when the user asks)
If the user wants a verified trace, also follow [RELIABILITY.md](RELIABILITY.md): a separate subagent checks each indirect hop. Do not run it by default. It costs the user's subscription.
## Not in scope
No edits to the repo, no running the code under study, no network calls. A flow that leaves the repo ends there, and the card says so.
Files in this package (7)
- README.md 2 KB
- RELIABILITY.md 4 KB
- SKILL.md 3 KB
- TEMPLATE.md 4 KB
- .claude-plugin/plugin.json 1 KB
- examples/codemap-pipeline.md 40 KB
- scripts/cite.py 6 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · capgoblin/codemap | 90 | MIT |
| jordancoin/codemap | 100 | MIT |
| AZidan/archflow | 100 | MIT |
| alvinunreal/oh-my-opencode-slim | 100 | MIT |
| jordancoin/codemap | 100 | MIT |
| ils15/copilot-global-config | 100 | MIT |
| azidan/codemap | 100 | MIT |
| ialameh/sift-coder | 100 | MIT |
| jellydn/my-ai-tools | 96 | MIT |
Database snapshot: 13.11.2026 · package version 3e19d50b8057 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90rc-codemap
Builds and refreshes per-directory codemap.md as a cheap structure map. Use before exploring a large repo. Do not use to trace one bug. - 90sequence-flow
Use when the user wants to see how a request, command or feature actually runs: call order, "what happens when X", runtime flow, or sequence diagrams. Traces real calls through the code and writes docs/codemap/sequence-flow.md. - 100architecture-overview
Use when the user wants an architecture overview, system structure, "how is this project organized", or C4-style diagrams of a codebase. Reads the code and writes docs/codemap/architecture.md with three zoom levels as Mermaid diagrams. - 100codemap-export
Use to export the codemap as machine-readable JSON for downstream tooling. Same data as /codemap, different format. "Export the codemap", "give me the codemap as JSON". - 90flow-map
Draws how something flows from A to B as three small Mermaid diagrams, checked against its sources, saved as Markdown beside them and kept current. Targets - a repo, several repos or a monorepo, a plain folder, or documents (Markdown, Word, PDF). Use to see, map or "understand… - 100code-flow-tracer
Trace code execution paths and data flow. Use when user asks "how does X work", "what happens when X", "trace the flow of X", "where does data come from", or needs to understand feature implementation.