Skip to content

Teach Me The Codebase

Bucket: Engineering · Slash command: /zsl:teach-me-the-codebase · Source: skills/engineering/teach-me-the-codebase/SKILL.md

User-invocable only

This skill is marked disable-model-invocation: true — Claude won't auto-trigger it, so you must invoke it explicitly with the slash command above.

What it does

On-the-fly conversational tutor that teaches you an unfamiliar repo's domain, architecture, and conventions interactively — reading the canonical docs and code, never writing them. Use when onboarding to a new codebase, when you ask to be taught or walked through how a repo works, or when you want to understand a project's structure before changing it.

An interactive onboarding tutor. You're new to this repo (or returning to a corner of it you've forgotten) and want to understand it — the domain it models, how it's put together, and the conventions it follows — before you touch anything. This skill teaches that, conversationally, in the session. It produces no persisted artefacts: there are no lessons/, no learning-records/, no progress files. The value is the understanding you walk away with, not a folder of notes.

Teacher-only boundary

This skill reads, it never writes the repo's canonical knowledge. It is a teacher, not an author:

  • It reads the existing CONTEXT.md (and CONTEXT-MAP.md if the repo is multi-context), the ADRs in docs/adr/, CLAUDE.md / AGENTS.md, and the code itself.
  • It never writes CONTEXT.md, never creates a parallel glossary, never edits ADRs. If, while teaching, you hit a term the docs don't define or a decision the ADRs don't record, that's a gap in the canonical docs — and authoring them is a different job. Hand it off:
  • An undocumented domain term → /grill-with-docs (it sharpens the term and writes it into CONTEXT.md using the domain-modeling CONTEXT format).
  • A load-bearing decision the code makes but no ADR explains → /grill-with-docs again, which offers an ADR via the domain-modeling ADR format when the decision is hard-to-reverse, surprising, and a real trade-off.

Surface the gap to the user and offer the hand-off; don't silently paper over it with your own glossary.

How to teach

  1. Get your bearings from the canonical docs first. Read CONTEXT.md, the ADRs, and CLAUDE.md/AGENTS.md before diving into code — they're the repo's own account of its domain language, decisions, and conventions. Use that vocabulary when you explain, so the user learns the repo's real terms (not invented ones).
  2. Ask what they want to learn, and at what altitude. "The whole system at a glance", "how requests flow end-to-end", "this one module", "the domain model" — pick a starting altitude and zoom from there.
  3. Teach in a loop, one thread at a time. Explain a piece, ground it in the actual files (cite path:line), then check understanding and follow the user's questions. Prefer the code and docs as evidence over assertion. When the user uses a fuzzy term, reach for the canonical one from CONTEXT.md and say where it came from.
  4. Connect each piece back to the whole. Architecture is only useful in context — relate a module to the layer it sits in, the seam it lives behind, the ADR that shaped it.

Optional cheat-sheet (on demand, never persisted)

If the user wants something to refer back to, offer to render a one-page summary of what you covered as a self-contained HTML cheat-sheet via the md-to-html skill — handed to them as a file to keep or discard. This is opt-in and ephemeral: offer it, don't auto-generate it, and never commit it into the repo (no docs/onboarding/, no checked-in notes). The teaching lives in the conversation; the cheat-sheet is a convenience, not an artefact the repo carries.

When to reach for a different skill

  • The docs are missing the term/decision you needed → /grill-with-docs (author it properly; this skill won't).
  • You want to change the architecture, not just understand it → /improve-codebase-architecture.
  • You're about to build a slice and want to align on the plan → /grill-with-docs then /to-prd.