Skip to content
Back to search

walkthrough

A Claude Code skill that generates interactive HTML walkthroughs with clickable Mermaid diagrams to explain codebase features, flows, and architecture.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexanderop--walkthrough/badge.svg)](/listings/alexanderop--walkthrough)

HTML

<a href="/listings/alexanderop--walkthrough"><img src="/api/listings/alexanderop--walkthrough/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick install

npx skills add https://github.com/alexanderop/walkthrough --skill walkthrough

Manual install

Copy the `skills/walkthrough/` directory into your project's `.claude/skills/` folder:

your-project/
  .claude/
    skills/
      walkthrough/
        skill.md
        references/
          html-patterns.md

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 157 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Walkthrough Skill
  2. A skill that generates interactive HTML walkthroughs with clickable Mermaid diagrams — flowcharts and ER diagrams — to explain codebase features, flows, architecture, and database schemas.
  3. Inspired by [Amp's Shareable Walkthroughs](https://ampcode.com/news/walkthrough).
  4. ## What it does
  5. Ask your agent to walk you through any part of your codebase and it produces a self-contained HTML file with:
  6. - A **clickable Mermaid diagram** (flowchart or ER diagram) showing the key concepts and their connections
  7. - A **detail panel** for each node with a plain-English description, file paths, and code snippets
  8. - **Pan and zoom** — scroll to zoom, drag to pan, auto-fit on load
  9. - **Syntax highlighting** via Shiki for every node's code snippet
  10. - **Dark mode** — pure black background, white text, purple accents
  11. The goal is fast onboarding: give a new developer a mental model of how something works in under 2 minutes. Not a code reference — a map.
  12. **[Live demo — walkthrough of the walkthrough skill itself](https://alexanderop.github.io/walkthrough/examples/walkthrough-how-it-works.html)**
  13. ![Generated walkthrough example](image.png)
  14. ## Usage
  15. Trigger the skill with prompts like:
  16. ```
  17. walkthrough how does authentication work
  18. explain this flow
  19. walk me through the checkout process
  20. how does X work
  21. database schema
  22. explain the tables
  23. ```
  24. The agent will:
  25. 1. Explore the relevant parts of your codebase using parallel subagents
  26. 2. Synthesize findings into 5-12 key concepts and their connections
  27. 3. Generate a single `walkthrough-{topic}.html` file in the project root
  28. 4. Open it in your browser
  29. ## Examples
  30. **Feature flow:**
  31. > Use the walkthrough skill and explain the process of what happens when a user submits a form.
  32. **Architecture overview:**
  33. > Walk me through how the plugin system is organized.
  34. **Database schema (ER diagram):**
  35. > Use the walkthrough skill and explain how the invites entity is stored in the database. Use an ER diagram.
  36. **Data flow:**
  37. > How does state flow from the composable to the component?
  38. ## Installation
  39. ### Quick install
  40. ```bash
  41. npx skills add https://github.com/alexanderop/walkthrough --skill walkthrough
  42. ```
  43. ### Manual install
  44. Copy the `skills/walkthrough/` directory into your project's `.claude/skills/` folder:
  45. ```
  46. your-project/
  47. .claude/
  48. skills/
  49. walkthrough/
  50. skill.md
  51. references/
  52. html-patterns.md
  53. ```
  54. ## Structure
  55. ```
  56. skills/walkthrough/
  57. skill.md # Main skill definition
  58. references/
  59. html-patterns.md # HTML template, CSS, and JS patterns reference
  60. ```
  61. - **skill.md** — The skill prompt that the agent follows. Defines the workflow: scope understanding, parallel codebase exploration, diagram type selection, and HTML generation.
  62. - **references/html-patterns.md** — Complete reference for the generated HTML files: React component architecture, Mermaid config, Shiki setup, color palette, pan/zoom implementation, and all the patterns needed to produce a working walkthrough.
  63. ## Tech stack (generated files)
  64. The output HTML files are fully self-contained with CDN dependencies:
  65. - **React 18** (UMD) — component rendering via `React.createElement()`
  66. - **Tailwind CSS** (CDN) — utility-first styling
  67. - **Mermaid 11** — diagram rendering (flowcharts and ER diagrams)
  68. - **Shiki** (ESM) — syntax highlighting with `vitesse-dark` theme
  69. No build step. Just open the HTML file in a browser.
  70. ## Testing
  71. The `evals/` directory contains an eval harness that runs the skill against a set of test prompts and grades the output.
  72. ### Prerequisites
  73. - `claude` CLI installed and authenticated
  74. - Node.js >= 18
  75. ### Running evals
  76. ```bash
  77. # Run all 16 test prompts
  78. bash evals/run.sh
  79. # Run only the 4 critical prompts (faster feedback loop)
  80. bash evals/run.sh --subset
  81. # Run a single prompt by ID
  82. bash evals/run.sh --id explicit-01
  83. # Skip the LLM rubric grader (deterministic checks only)
  84. bash evals/run.sh --skip-llm
  85. # Use a specific model (default: sonnet)
  86. bash evals/run.sh --model opus
  87. ```
  88. You can also set defaults via environment variables:
  89. ```bash
  90. EVAL_MODEL=opus EVAL_MAX_BUDGET=3.00 bash evals/run.sh
  91. ```
  92. ### How it works
  93. Each eval run:
  94. 1. Copies the project into a temp directory with the skill installed
  95. 2. Runs `claude -p` with each prompt from `evals/prompts.csv`
  96. 3. Collects any generated `walkthrough-*.html` files
  97. 4. Runs two graders:
  98. - **Deterministic** (`graders/deterministic.mjs`) — checks file existence, HTML structure, CDN deps, node count, diagram type
  99. - **LLM rubric** (`graders/llm-rubric.mjs`) — uses Claude to score readability, descriptions, code snippets, and diagram accuracy against `graders/rubric.md`
  100. 5. Generates a summary report in `evals/results/<timestamp>/summary.json`
  101. Results are saved to `evals/results/` (gitignored). A `latest` symlink always points to the most recent run.
  102. ### Test prompts
  103. The prompts in `evals/prompts.csv` cover:
  104. - **Explicit triggers** — `$walkthrough how does X work`
  105. - **Implicit triggers** — `walk me through X`, `explain the flow`
  106. - **Diagram types** — flowchart and ER diagram cases
  107. - **Negative cases** — prompts that should *not* trigger the skill
  108. - **Edge cases** — vague prompts, broad scope

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.