Codebase Explainer
Produces a guided walkthrough of an unfamiliar codebase — entry points, key modules, data flow, and where to make a change.
What this skill does
Key features
- Identifies real entry points and traces execution from them
- Maps key modules and how data flows between them
- Points to where a given change would go, with file:line
- Cites file:line for every claim and never invents behavior
Use cases
- Onboarding onto an unfamiliar repository
- Deciding where a new feature should live
- Understanding how a request flows end to end
SKILL.md
The skill definition — its metadata and the exact instructions an agent follows. Copy it into a SKILL.md file in your agent's skills folder.
| name | code-explainer |
|---|---|
| description | Explain an unfamiliar codebase: entry points, key modules, data flow, and where to make a change. |
| allowed-tools | Read, Grep, Glob |
| output | guided codebase walkthrough |
| citations | file:line required |
Musts
- Find the real entry points (main, server bootstrap, CLI, route registration) before explaining anything, and start the walkthrough there.
- Cite file:line for every structural claim; if you did not open the file, do not assert what it does.
- Trace at least one concrete path end to end (e.g. a request or command) showing how data moves between modules.
- When asked where to make a change, point to the specific file and location and explain why it belongs there.
- Distinguish what you verified from what you inferred; mark inferences and unknowns explicitly.
Guidelines
- Lead with the mental model a newcomer needs, then drill into modules — breadth before depth.
- Prefer naming the few modules that matter over listing every file.
- Note conventions (naming, layering, error handling) that a contributor must follow.
- Keep it honest: if the architecture is inconsistent or unclear, say so rather than smoothing it over.
Output format
## Overview
<2-3 sentences: what this codebase does and its shape>
## Entry points
- <name> — <file:line> — <what starts here>
## Key modules
- <module> — <file:line> — <responsibility>
## Data flow: <one concrete path>
1. <step> (<file:line>)
2. <step> (<file:line>)
## Where to make <change X>
- <file:line> — <why here>
## Unverified / unknowns
- <thing you could not confirm>FAQ
Will it make up behavior it did not read?
No. Every claim is backed by a file:line it actually opened. Where behavior is unclear or depends on runtime config, it says so instead of guessing.
Does it change any code?
No. It only reads and explains. When you ask where to make a change, it points to the location and rationale but leaves the editing to you or a separate step.
Before running any skill, read its instructions and the tools it's allowed to use, and test it on a safe target first. See LLM security best practices.