Explain Diff (HTML)

A Claude Code skill that turns a code change into one self-contained HTML page that teaches a reader what changed and why.

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.

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.

If you're investigating a bug, you can ask the skill to do a root cause analysis, bug investigation, or bug identification report as additional context.

The skill can use that alongside the actual code changes to connect the reported issue with the implementation and explain not just what changed, but also what went wrong, where it went wrong, and why the fix works.

If you already have an RCA or investigation report from your team, you can provide that too.

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 reads the code around the diff, then 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, with one exception.

That exception is Mermaid, 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.

Limitations below sets out what it deliberately does not do.

Samples

Seven samples across three languages, each explaining a merged pull request in a public repository.

The Page links go 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.

Page	Repository	Pull request	What it teaches
PR 11305	TanStack/query, TypeScript	11305	A ?.field guard answering two questions at once, so falsy errors never reached the error boundary
PR 11242	TanStack/query, TypeScript	11242	A guard that reset only on the happy path, and why the fix uses finally with no catch
PR 16102	fastapi/fastapi, Python	16102	A three-valued option collapsed at the public boundary, and the stack depth a warning depends on
PR 16013	fastapi/fastapi, Python	16013	Double-checked locking and build-then-publish, and why the list is assigned before the version
PR 2924	uPortal, Java	2924	A catch that logs and falls through, and an @Ignore that had been skipping 30 tests
PR 2945	uPortal, Java	2945	Picking the type that matches the intent, so a static-analysis suppression stops being needed
PR 2983	uPortal, Java	2983	An implicit path attribute made explicit, moving resolution from the server to the browser

Each page has been through two checks: a read-only pass that re-opens every cited file:line at the pull request head and tries to falsify each claim, and a cold read of the prose against the writing rules in SKILL.md, the file that defines the skill.

Requirements

Tool	Needed when	Used for
git	Every run	Resolving the base, fetching the ref, reading the diff
gh	Explaining a pull request	Fetching the pull request title, body, and URL
node	Every run that carries a Mermaid diagram	Validating Mermaid sources in step 4, through npx

gh must be authenticated, not only installed. Check with gh auth status.

Node is a build-time validator only. Nobody needs Node to open a finished page, because the reader's browser loads Mermaid from the CDN.

The skill's commands are POSIX shell, so it runs on Linux and macOS directly, and on Windows through WSL or Git Bash. Windows PowerShell and cmd.exe are not supported: they have no command -v, no $(...) substitution, and none of mktemp, sed, or openssl. The generated page itself is plain HTML and opens in any browser on any platform.

Install

The repository root is the skill, so cloning it into place is the whole install.

For every project you work on:

git clone https://github.com/malav2110/explain-diff-html.git \
  ~/.claude/skills/explain-diff-html

For one project only, committed alongside the code so your team gets it too:

git clone https://github.com/malav2110/explain-diff-html.git \
  <your-repo>/.claude/skills/explain-diff-html

Claude Code reads SKILL.md. The README.md and samples/ directory sit in the same folder and are ignored, so nothing needs moving or deleting.

Confirm the install by asking Claude Code to list its skills, or by running /skill-doctor if your version has it. explain-diff-html should appear with its description.

Use

Ask in plain language. The skill triggers on phrasing like this:

explain PR 1234
explain this diff
walk me through this branch
explain the changes between abc123 and def456

It writes the page to a code-explanations folder in your home directory, $HOME/code-explanations, named YYYY-MM-DD-<KEY>-explanation.html, and reports the path. The date comes first so the files sort by time, and the key comes second so you can grep for a ticket or a pull request later. <KEY> is an issue key such as PROJ-1234 when the branch name carries one, otherwise pr-1234, otherwise a short slug.

Output lands outside the repository on purpose. An explanation is not a project artifact, and writing it into the working tree invites committing it by accident.

Limitations

It explains a change. It does not critique one.

The page will not tell you whether the change is correct, whether the approach is right, or what to fix. There are no findings, no severity ratings, and no verdict anywhere in it. Read it to understand a pull request before you review it, or to learn a codebase from changes someone else made. The reviewing is still yours.

The page also describes the pull request in whatever form it has when you run the skill. It is a snapshot of one diff at one ref. If the author pushes three more commits afterwards, the page still describes what it read, and nothing in it updates. Generate a new page rather than trusting an old one.

One more thing to know: it explains what the record supports. Where the reasoning behind a change is not in the diff, the commits, the pull request body, or the repository's own documents, the page says so rather than inventing a motive.

How it works

SKILL.md drives Claude Code through eight steps. In outline:

1. Resolve the target and the filename key, detecting the repository's default branch rather than assuming main.
2. Gather context: the code around the diff, the pull request body, the commit messages, and any design records the repository keeps.
3. Draft the four sections, walking the code in flow order.
4. Build the diagrams, from three dependency-free HTML and CSS families plus Mermaid for state, entity-relationship, and sequence shapes.
5. Write the quiz to the question shapes that test transfer rather than recall.
6. Hand the prose to a fresh reader for an editing pass, because an author misses its own tells.
7. Run the self-check, including re-reading every cited file:line at the target ref.
8. Write the file.

Step 7 carries two checks that exist because of specific failures. It confirms every code block is HTML-escaped, because a single raw < in a pasted diff line opens an element HTML never closes, which swallows the rest of the document and breaks every anchor below it. It also re-reads each cited line at the target ref, because a stale ref produces line numbers that look right and point at nothing.

Customizing

Everything visual lives in html-template.html, which the skill fills in rather than rebuilding per run:

• Colors are CSS custom properties at the top, in a light set and a dark set. Change the two blocks to match your own palette.
• The three hand-built diagram families are plain markup: a simplified UI mockup, a data-flow diagram with example payloads on the arrows, and a node tree for recursive structures.
• The Mermaid loader pins an exact version and checks it with a Subresource Integrity hash. To change versions, edit the @x.y.z in the src and recompute the hash. SKILL.md carries the command. A stale hash makes the browser block the script and the diagrams then fail silently.
• The output directory and the filename pattern are in SKILL.md, under the output contract.

License

MIT. See LICENSE.