Skip to content
Skills Library
Programming · Writing

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.

Repository
codemap ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

how does X worktrace Xmap what happens when Y
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

  1. Rules
  2. Steps
  3. Choices already made
  4. Strict mode (only when the user asks)
  5. Not in scope
Original SKILL.md headings · 40 lines, 498 words
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

RepositoryScoreLicence
This page · capgoblin/codemap90MIT
jordancoin/codemap100MIT
AZidan/archflow100MIT
alvinunreal/oh-my-opencode-slim100MIT
jordancoin/codemap100MIT
ils15/copilot-global-config100MIT
azidan/codemap100MIT
ialameh/sift-coder100MIT
jellydn/my-ai-tools96MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.