Codebase Onboarding Guide
Explains any unfamiliar codebase top-down: entry points, data flow, and the weird parts.
An agent skill for explaining unfamiliar code the way a great senior engineer onboards you: entry points first, then the core data flow, then where each concern lives — with honest flags on the confusing parts and the landmines, instead of a file-by-file inventory.
SKILL.md
---
name: codebase-guide
description: Explain a codebase or module to someone new to it. Use when asked "how does this work", "explain this repo/module", or during onboarding tasks.
---
# Codebase Onboarding Guide
When explaining a codebase or module, investigate first, then explain top-down.
## Investigation (do this before explaining)
- Find the true entry points (main, route registration, event handlers) — don't trust the README's claim, verify
- Trace ONE representative request/operation end to end
- Check tests for behavior documentation; check git log for the most-churned files (that's where the action is)
## Explanation structure
1. **What it does** — one paragraph, plain language, no file names yet
2. **The mental model** — the 3-5 core concepts and how they relate ("a Job is created by X, queued in Y, executed by Z")
3. **Follow one request** — trace a concrete operation through actual files with file:line references
4. **Where things live** — map of concerns to directories, ONLY the ones that matter for the reader's task
5. **The weird parts** — honest flags: surprising patterns, legacy layers, things named misleadingly, the file everyone is afraid of
6. **Where to start** — for the reader's specific goal, the 2-3 files to read first
## Rules
- Depth follows the reader's need: onboarding tour ≠ pre-change deep-dive; ask which if unclear
- Verified claims only — every "X calls Y" must come from read code, not inference from names
- Flag dead code and stale docs when found; don't describe aspirational architecture as currentTry it out
Open in Playground →Run this skill on a real model without leaving the page. Every run is saved to your history for this skill.
How to use
- 1Save as .claude/skills/codebase-guide/SKILL.md.
- 2Ask 'how does auth work in this repo?' or 'explain this module before I change it' — the skill shapes the answer.
- 3The 'weird parts' section is the institutional knowledge that usually takes months to acquire — read it first.
Examples
Onboarding to a payment service
Input
'Explain how this billing service works, I need to add a new payment method.'
Output
**Mental model**: three concepts — PaymentMethod (strategy interface), PaymentIntent (state machine: created→authorized→captured), and the ReconciliationJob... **The weird parts**: `utils/stripe_helpers.py` is misnamed — it contains the core retry logic for ALL providers... **Where to start for your goal**: read PaymentMethod interface (methods/base.py:12), then the PayPal implementation as your template...
Pro tips
- Re-run it after 6 months away from a codebase you wrote yourself. Humbling and useful.
Frequently asked questions
How big a codebase can this handle?+
The skill scopes exploration to the reader's goal, so it works on large monorepos — it traces one path well instead of summarizing everything badly. For whole-system architecture docs, run it per subsystem.