explain-diff-html

Explain Diff (HTML)

An agent skill that turns a code change into one self-contained HTML page that teaches a reader what changed and why. It runs in Claude Code, Codex, Cursor, and every other agent the skills installer reaches.

Demo generated by the brag skill.

Origin

This started from Geoffrey Litt's explain-diff gist, which set out the four-section structure, the quiz, the self-contained HTML output, and the skill's name. This version adds flow-ordered walkthroughs, verified file:line anchors at the target ref, Mermaid diagrams with validation, a provenance line, and a set of checks built from specific failures.

This version also adapts work from Cat Hicks' learning-opportunities skill: three of the quiz question shapes, and the rule that difficulty belongs in the stem rather than in near-identical options. That skill is CC-BY-4.0.

It was written as a Claude Code skill, and SKILL.md keeps that format. Other agents read the same format now, so npx skills add installs it elsewhere without changing the file.

Why this exists

AI is helping us write code faster than ever.

That's great, but there's also a side effect: we're generating more code, reviewing bigger changes, and sometimes understanding less of what actually happened.

You open a PR and suddenly there are hundreds, maybe thousands, of changed lines across a bunch of files.

Git shows you the diff file by file.

controller.ts

service.ts

utils.ts

tests...

But that's usually not how the change actually works.

So where do you start?

Which file matters first? What calls what? Why was the change needed? How does the data move through the system?

And that's where PR reviews can start becoming difficult.

For me, PRs have always been one of the best ways to learn a codebase. You look at someone else's changes, follow the flow, understand why they made certain decisions, and slowly build a better mental model of the system.

As AI generates more of the implementation and PRs keep getting larger, I didn't want to lose that learning opportunity.

That's where explain-diff-html came from.

Instead of explaining a change in the order Git happens to show the files, it tries to follow the logical flow of the code.

So instead of:

file A → file B → file C

it might explain it as:

request → handler → service → transformation → result

It looks at the diff, the surrounding code, callers, related definitions, commits, and documentation, then turns all of that into a walkthrough that tries to answer a simple question:

"If I actually want to understand this PR, where should I start and how does everything connect?"

And it's not limited to PRs.

Hand it a bug investigation or an RCA alongside the diff, and it connects the reported failure to the fix.

Where it helps, below, covers that and the other uses.

The goal isn't just to tell you what changed.

The goal is to help make PR reviews, debugging, and code investigation a learning opportunity again.

What it produces

Point it at a pull request, a branch, or a commit range. It reads the diff, then the code around it, and writes a single page with four sections:

• Background, on the system the change lands in, with the beginner-level part collapsed so a familiar reader can skip it.
• Intuition, on the core idea, with toy data and diagrams rather than full detail.
• Code walkthrough, ordered by the path a request or an action takes through the system, not by filename.
• Quiz, five interactive multiple-choice questions that test whether the reader understood why the change is shaped the way it is.

The output is one HTML file with the CSS and JavaScript inline. It opens with a double click, reads on a phone, and follows the reader's light or dark system theme. Nothing needs a server, a build step, or a network round trip, apart from Mermaid.

Mermaid is the diagramming library these pages use for state, entity-relationship, sequence, and flow diagrams. A page carrying one of those loads Mermaid from a CDN, so it needs network for those diagrams to draw. Everything else on the page, including the hand-built diagrams and the quiz, works offline.

Where it helps

The main use is reading a pull request before you review it. Three others come up often.

Onboarding. Point it at the old merged pull request that introduced something foundational rather than at documentation written a year ago. A new hire gets a walkthrough built from the code as it actually is.

Large or machine-written changes. Git orders a diff by path, so a change spanning controllers, services, and models arrives in an order nobody wrote it in. The page orders it by the path a request takes. That matters most on pull requests an agent produced, where the volume outruns what a reviewer can hold at once.

Bug fixes and post-mortems. Hand the skill your incident report or investigation notes alongside the diff. The page connects the reported failure to the fix, so the reader sees where the bug lived and why the patch closes it.

Samples

Nine samples across four languages, all from public repositories. Eight explain one merged pull request. The ninth explains a whole release, 94 commits across 417 files, to show what the skill does when the target is bigger than a single change.

The first column links to the rendered pages on GitHub Pages. Opening the same files from the samples/ directory in this repository shows their HTML source instead, because GitHub serves .html as code rather than rendering it.