Walkthrough Skill
A skill that draws a clickable Mermaid diagram in HTML: how a feature, a data flow or database tables work, with code per node
- 149 ★ on the repository
- Last commit
Extended access
Why this level
- The skill reads project source through subagents and writes a `walkthrough-*.html` file into the repository root.
- The generated page loads scripts from a CDN and shows snippets of your code in the detail panel.
Install
- Works in
Manual install
npx skills add https://github.com/alexanderop/walkthrough --skill walkthroughThe skills installer places `walkthrough` into the agent directory.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill reads project source through subagents and writes a `walkthrough-*.html` file into the repository root.
- The generated page loads scripts from a CDN and shows snippets of your code in the detail panel.
This is third-party code. Review the repository files before installing.
What it does
Walkthrough Skill creates one self-contained `walkthrough-{topic}.html` file in the project root and opens it in a browser. Inside is an interactive Mermaid diagram (flowchart or ER diagram): clicking a node opens a panel with a plain-English description, file paths and a Shiki-highlighted code snippet. The diagram can be dragged and zoomed with the wheel, and it fits the screen on load. Before drawing, the agent explores the relevant part of the codebase with parallel subagents and reduces the findings to 5-12 concepts and the links between them. The author's goal is to give a new developer a mental model of how something works in under two minutes. The result is a map, not a code reference. The skill triggers on prompts like "walkthrough how does authentication work", "walk me through the checkout process" and "database schema". Calling `$walkthrough` with no topic builds an overview of the whole project. The design is always dark: black background, white text, purple accents.
Who it is for. Developers joining an unfamiliar project, and documentation authors who need a picture of a request path or table relationships.
Good fit when
- A new developer is onboarding and needs a map: what happens after a form is submitted.
- A plugin module or application layers should be shown as a diagram instead of five paragraphs of text.
- Table structure and relationships have to be explained on an ER diagram with code snippets.
- A state path from component to store has to be traced through files and drawn.
Not a fit when
- A precise reference of functions and arguments is needed: a diagram of 5-12 nodes will not replace it.
- A short text answer in chat is wanted: the skill always creates an HTML file and never answers with text alone.
- A machine without network or behind a closed proxy: the page pulls its libraries from a CDN.
Example request
Use the walkthrough skill and explain what happens when a user submits the signup form, from the component to the database write.Limitations
The last commit in the repository dates from March 2026 and there is no license file. The page loads React 18, Tailwind, Mermaid 11 and Shiki from a CDN, so the diagram does not render without a network. The theme is dark only. The main skill file sits in `skills/walkthrough/skill.md` in lowercase and the page template in `references/html-patterns.md`. The skill is built for Claude Code and similar products and needs a browser to open the result.
How to disable. Delete the `walkthrough` directory from the project's `.claude/skills/` (or the global skills directory) and the generated `walkthrough-*.html` files from the project root.
FAQ
How do I install Walkthrough Skill?
Run `npx skills add https://github.com/alexanderop/walkthrough --skill walkthrough`. For a manual install, copy the `skills/walkthrough/` directory into the project's `.claude/skills/`.
Which diagrams can the skill build?
Two kinds: a flowchart for flows, architecture and request lifecycles, and an ER diagram for database tables and data models.
What happens if I call $walkthrough with no topic?
The skill builds an overview of the whole project: the main modules and how they connect.
Why does the skill launch subagents?
They read different parts of the code in parallel, and the skill assembles 5-12 diagram nodes from their findings. A big feature gets covered faster than with sequential reading.
Can the result be opened without internet?
No, the diagram will not render: React, Tailwind, Mermaid and Shiki load from a CDN. You can save the file and open it where a network exists.
Discussion
No questions or reviews yet.
Related
SkillsA Claude Code skill that builds diagrams of 23 types from a syntax reference bundled in the repository, called with /mermaid.
A skill that replaces terminal ASCII with self-contained HTML pages: diagrams, diff reviews, plan reviews, tables and slide decks
A skill that generates and renders Mermaid diagrams as SVG, PNG or ASCII: 15 themes and several diagram types, locally without a browser
A skill maps project architecture, rules and proposed edit scope in an HTML page so users can approve a plan before code changes.
A skill that turns an architecture discussion into an interactive isometric map of the system and a SYSTEM.md text twin from one data file
A Codex skill for reviewing AI-written code: explains blocks, names files and lines, checks goals against evidence.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Walkthrough Skill (this card) | no | 149 | |
| Oh-my-mermaid | no | 3,380 | also draws Mermaid diagrams from code; here the result is a finished page with a detail panel and code per node |
| Codebase to Course | no | 5,770 | turns code into a course; here one feature map of 5-12 nodes for a quick start |
README in short
The README describes the shape of the result, gives example prompts and two install paths. The second half covers the checks in `evals/`: 16 test prompts, a deterministic file check and a rubric grading run through Claude.
README badge
Original SKILL.md
---
name: walkthrough
description: >
Generates a self-contained HTML file with an interactive, clickable Mermaid diagram
(flowchart or ER diagram) that explains how a codebase feature, flow, architecture,
or database schema works. Designed for fast onboarding — each walkthrough is a visual
mental model readable in under 2 minutes.
TRIGGER this skill when ANY of these match:
- The prompt starts with or contains "$walkthrough" (explicit trigger — always activate, even if no topic follows)
- The user asks to "walk me through", "walkthrough", "trace the code path", "explain this flow",
"show how X works", "how does X work step by step", "explain the architecture",
"visualize the data model", "show the data structures", "show the relationships"
- The user wants a visual/interactive explanation of code, flows, pipelines, or schemas
When triggered, ALWAYS generate a walkthrough HTML file — never respond with just text.
If "$walkthrough" is used with no topic, generate an overview walkthrough of the entire project.
compatibility: Designed for Claude Code (or similar products). Requires a browser to open generated HTML files.
allowed-tools: Bash Read Write Glob Grep Task
metadata:
author: Alexander Opalic
version: "1.1"
---
# Codebase Walkthrough Generator
Generate interactive HTML files with clickable Mermaid diagrams that give new developers a **quick mental model** of how a feature or system works. The goal is fast onboarding — a rough map of concepts and connections, not a code reference. Each walkthrough should be readable in under 2 minutes.
**CRITICAL**: When this skill is triggered, you MUST generate a `walkthrough-*.html` file. Never respond with just text — always produce the interactive HTML output.
**Always dark mode.** Every walkthrough uses a pure black background (`#000000`), white text, and purple accents. Never generate light-mode walkthroughs. The `<html>` tag MUST include `style="color-scheme: dark"`.
## Workflow
### Step 1: Understand the scope
Clarify what the user wants explained:
- A specific feature flow (e.g., "how does canvas drawing work")
- A data flow (e.g., "how does state flow from composable to component")
- An architectural overview (e.g., "how are features organized")
- A request lifecycle (e.g., "what happens when a user clicks draw")
- A database schema (e.g., "explain the tables and relationships")
- A data model (e.g., "how is user data structured")
If the prompt is `$walkthrough` with no topic, generate an **overview walkthrough of the entire project** — show the main modules, how they connect, and the overall architecture.