Explain Codebase

Explain Codebase

Produce a clear, accurate orientation for someone seeing this project for the first time. The audience may be new to the stack — favor plain language and concrete file paths over jargon.

This skill is strictly read-only. It does not edit, run mutating commands, or install anything.

How to build the tour — read, don't guess

Ground every claim in a file you actually read. Don't infer architecture from the framework's reputation; confirm it in the code. Work through these, in roughly this order:

1. What is it? Read README.md, package.json/composer.json/pyproject.toml description,

and any docs/ index. State the project's purpose in 1–2 sentences. If it's genuinely unclear, say so rather than inventing a mission.

1. Stack — invoke /webdev:detect-stack and report the framework, language, package

manager, test runner, and build tool. Note the major dependencies that shape the architecture (ORM, state manager, UI library, auth).

1. Layout — map the top-level directories to their roles (src/, app/, routes/,

components/, tests/, config/, etc.). One line each. Skip vendored/generated dirs.

1. Entry points — where execution starts: the server bootstrap, the router/route definitions,

the main app component, the CLI entry, background workers. Cite the actual files.

1. Data model — the core entities/models/tables and their relationships, if there's a clear

data layer. Point at the schema/migrations/models directory.

1. How to run it — the resolved dev, test, and build commands (from /webdev:detect-stack),

plus any required setup the README calls out (env file, services, seed data). Don't run them; just report them accurately.

1. Conventions — read CLAUDE.md, CONTRIBUTING.md, lint/format config, and a couple of

representative source files to surface the real patterns (naming, file structure, styling approach, how state/data flows). Cite an example file for each pattern you name.

1. Where to start reading — recommend the 3–5 files a newcomer should open first to understand

the app, in order, with one line on why each matters.

Scale to the ask

• "Quick overview" → sections 1, 2, 3, 6 only — a tight one-screen orientation.
• "Full tour" / "help me understand this deeply" → all eight, with more cited examples.
• A question about a specific area ("how does auth work here?") → focus the tour on that

subsystem: trace it end to end with file:line references, skip the rest.

Honesty rules

• If something is ambiguous or you couldn't find it, say so — "I didn't find a test setup" is

more useful than a confident guess.

• Don't present the framework's typical structure as this project's structure unless you

verified it in the files.

• Flag anything that looks surprising or risky in passing (no tests, secrets committed, a stalled

migration) — but don't turn the tour into an audit; that's /webdev:qa-review.

Output

A structured tour with clickable path / path:line references throughout:

• What it is (1–2 sentences) · Stack · Layout (dir → role)
• Entry points · Data model (if applicable) · How to run / test / build
• Conventions (with example files) · Start here (ordered reading list)
• Open questions / things I couldn't determine (if any)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jaballer
• Source: jaballer/claude-webdev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.