# Teach Codebase > Build a mental model of an unfamiliar codebase — architecture, subsystems, and where to look when changing something. Use when the user is new to a repo, is picking up a project they didn't write, or asks how a codebase is structured or where something lives. - Skill: `slikon/teach-codebase` (Agent Skill) - Install (CLI): `npx skillmds@latest add slikon/teach-codebase` - Raw SKILL.md: https://api.skillmd.com/api/skills/slikon/teach-codebase/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Slikon (https://skillmd.com/u/slikon) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/slikon/teach-codebase --- Teach the user this codebase the way a colleague would at a whiteboard: a short **lesson** they read once, top to bottom — not a reference file they look things up in. The reader finishes able to retell how the system works; they do not memorize facts from it. If arguments were passed, scope the lesson to that area. ## Steps ### 1. Check for an existing lesson Read `/.teach/codebase.md` if it exists (resolve root with `git rev-parse --show-toplevel`, else the current directory). Its frontmatter carries the commit it was generated at — run `git diff ..HEAD --stat` and update only what moved. If the diff is huge or the SHA is unreachable, start fresh. ### 2. Explore enough to tell the story Widening passes — structure and manifests, then entry points and config, then the main flow — and stop as soon as you can narrate one real run of the system end to end. If a code-index MCP is available (architecture or call-graph queries), use it instead of manual grep to find entry points and trace the flow. Trust code over documentation when they disagree. ### 3. Write the lesson Write `/.teach/codebase.md` with frontmatter (`commit:` from `git rev-parse HEAD`, `generated:` date). Three parts, in this order: **Part 1 — The idea.** What the system does and for whom, in a few lines. Then the one or two design decisions that explain everything else (for example: "there is no database — files on disk are the state"). Then one small overview diagram, **3–7 boxes**, concepts not filenames. **Part 2 — One run, start to finish.** The heart of the lesson. Pick the system's most representative operation — a request, a job, a build — and narrate it as a story: "You do X. First A happens (`file.py`), because ... Then B ...". Each step says what happens, which file does it, and why it is a separate step. Add a `sequenceDiagram` of this flow that matches the narration. Close Part 2 with a **module map**: one flowchart of the real modules, grouped into named `subgraph` blocks by role (front end, pipeline stages, shared services — whatever the system's real groupings are), with edges labeled by the data that flows between them. Grouping is the budget: at most ~5 groups of ~5 nodes each — name the groups, don't enumerate every file. This map comes *after* the story on purpose: a map only makes sense once the reader knows the journey. **Part 3 — Working in it.** A table mapping change to place — "To change X → open Y" — one line per row, no paragraphs. Then at most five warnings, each a single plain sentence: the mistake, what you will see, what to do instead. **Cut everything else.** No file inventories, no disk layouts, no lists of config options, no documentation audits, no branch or git state. Those facts live in the repo; the lesson exists to build the model, not to copy the data. If existing docs would actively mislead a reader, that is one warning line in Part 3, not a section. ### 4. Language and diagram rules - Write for a reader whose first language may not be English: short sentences, plain words, no idioms or colloquialisms ("gotcha", "trips you up", "load-bearing", "escape hatch"). If a domain term is unavoidable, define it in the same sentence. - Never show a naked diagram. One sentence before it stating the question it answers; one sentence after it pointing at the thing to notice. A diagram over ~8 ungrouped nodes gets grouped into subgraphs, split, or cut. - Explain **why** a thing exists whenever the code shows the reason. Mark guesses as guesses; label confidence only when it isn't high. Never invent a rationale. ### 5. Hand it back Print the path and offer to go deeper on any part. Target under ~150 lines, readable in five minutes. If it runs long, cut Part 3 detail — never Part 2. **Completion criterion:** after one top-to-bottom read, the user can retell how one real run moves through the system, and knows which file to open for each kind of change.