Skip to main content
skill CX Codex

explain-diff · nicknisi — Claude Code skill: explain changes and install

The explain-diff skill turns a diff, PR, branch, or commit into an HTML guide with system context, diagrams, a code walkthrough, and a quiz. Use it to understand a change or teach it to someone else.

MIT ★ 114 updated 2026-08-11

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add nicknisi/claude-plugins
/plugin install essentials@nicknisi
Open on GitHub

What explain-diff does

The skill first identifies what to inspect. For a PR, it uses gh pr diff and gh pr view; for a branch, git diff; for a commit, git show. If you give no target, it checks the working tree with git diff HEAD, then reads the changed files and the surrounding subsystem. That extra context shapes the explanation.

The output is a single HTML file with sections on the existing system, the change’s main idea, a guided code walkthrough, and an interactive quiz with five questions. CSS and JavaScript are embedded, with no external requests, so the file works offline. It is saved outside the repository under /tmp/ and opened in a browser. On macOS the skill uses open <path>, so that final step depends on browser access.

What it helps with

  • understand the purpose and effect of a PR
  • trace a change from its core idea into the code
  • prepare an explanation of a branch for a teammate
  • check understanding of a commit with a quiz

Example prompts for the agent

  • Explain this PR in an HTML guide, including the problem the change addresses.
  • Inspect the current branch against the default branch and write a guide for someone new to this codebase.
  • Walk me through this commit and add a quiz to check my understanding.

How to install explain-diff

1Plugin marketplace

/plugin marketplace add nicknisi/claude-plugins
/plugin install essentials@nicknisi

This installs the whole essentials plugin with all its skills

2Skills CLI (Vercel)

npx skills add nicknisi/claude-plugins --skill explain-diff -a claude-code

3Manually: put the files in place

~/.claude/skills/explain-diff/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/explain-diff/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about explain-diff

How do I install explain-diff in Claude Code?

Add the marketplace with /plugin marketplace add nicknisi/claude-plugins, then install the plugin with /plugin install essentials@nicknisi.

What does explain-diff do?

It examines a change and its surrounding code, then creates an HTML guide with system background, diagrams, a code walkthrough, and an interactive quiz.

Does the generated HTML work offline?

Yes. Its CSS and JavaScript are embedded, and it makes no external requests.

Source text

SKILL.md · MIT
---
name: explain-diff
description: >-
  Produce a rich, self-contained HTML explainer for a code change — deep
  background, core intuition with diagrams, a guided code walkthrough, and an
  interactive quiz. Use whenever the user asks to explain or deeply understand
  a diff, PR, branch, or commit — "explain this PR", "walk me through this
  change", "what does this diff actually do", "make an explainer for this
  branch" — or wants a shareable document that teaches someone else what
  changed and why. Output is an HTML file opened in the browser, not a chat
  reply.
---

# Explain Diff

Create a rich, interactive HTML explanation of a code change. The reader may be a teammate encountering the codebase for the first time or the author checking their own understanding — the document should serve both.

## Resolve the change

Pin down exactly what to explain before writing anything:

- **PR number or URL** — `gh pr diff <number>` for the diff, `gh pr view <number>` for the title, description, and discussion
- **Branch** — `git diff <base>...<branch>` against the repo's default branch
- **Commit** — `git show <sha>`
- **Nothing specified** — the working tree (`git diff HEAD`); if clean, the current branch against the default branch

Then explore beyond the diff: read the touched files in full, their callers, and the subsystem they belong to. The Background section lives or dies on your understanding of the surrounding system, not just the delta.

## Sections

The explanation has four sections, in this order:

1. **Background** — Explain the existing system this change slots into. The reader's familiarity is unknown, so layer it: a deep background for beginners (marked as skippable for readers who already know the system), then a narrower background directly relevant to the change.

2. **Intuition** — Explain the core idea of the change: what problem existed, what insight the change embodies, why this approach. Focus on the essence, not the full details. Use concrete examples with toy data, and use figures and diagrams liberally.

3. **Code** — A high-level walkthrough of the changes. Group and order them for understanding — by concept or data flow — not by file order in the diff.

4. **Quiz** — Five interactive multiple-choice questions testing whether the reader understood the substance. Medium difficulty: answerable only by someone who actually understood the change, but no gotchas. On click, reveal whether the answer was correct with a short explanation either way — the feedback is where the learning happens.

## Output format

Produce a single self-contained HTML file:

- All CSS and JavaScript inline, no external requests (CDNs, fonts, images) — the file is opened locally and must work offline.
- One long page with section headers and a table of contents. Don't use tabs for the top-level structure.
- Basic responsive styling so it reads well on a phone.
- Save it outside the repo so it stays out of version control, with the filename starting with today's date so the files stay time-sorted: `/tmp/YYYY-MM-DD-explanation-<slug>.html`.
- When done, open it in the browser (`open <path>` on macOS) and tell the user the path.

## Writing style

Write with the clarity and flow of Martin Kleppmann — engaging, classic style, with smooth transitions between sections. Use callouts for key concepts, definitions, and important edge cases.

## Diagrams

- Pick a small number of diagram families and reuse them throughout to explain different cases — a repeated visual form makes each new instance easier to parse. Useful families:
  - A simplified version of the UI the user sees in the app, for explaining UI changes.
  - A system diagram showing data flow or communication between components — always populated with example data.
- Build diagrams from simple HTML and CSS, and lists from HTML lists. Never use ASCII art — it breaks under responsive layouts and proportional fonts.
- Use `<pre>` tags for code blocks. If a custom-styled div is used instead, its CSS **must** include `white-space: pre` or `pre-wrap`, or the browser will collapse every newline into a single line. Before saving the file, scan each code block in the HTML source and confirm its whitespace handling.

© Nick Nisi · MIT · nicknisi/claude-plugins

Similar skills

All skills for Git and GitHub →

explain-diff by other authors comes first.

explain-diff claesbackman The explain-diff skill turns a code-change review into a standalone HTML page with a quiz. Use it to explain a diff and examine its effects on empirical results. CX Codex +1 ★ 579repo stars tasks-explain-diff makenotion tasks-explain-diff turns code changes into a structured Notion document with architecture context, diagrams, and verification steps. Useful when documenting PRs for team handoffs. CX Codex +1 ★ 40repo stars understand-diff Egonex-AI understand-diff analyzes Git diffs against the project knowledge graph to identify affected dependencies, architectural layers, and merge risks. Useful before reviewing pull requests. CX Codex +1 4,200installs diff-analyze ruvnet diff-analyze analyzes a git diff before a PR, scoring risk, classifying changes, and suggesting reviewer roles. Use it before merging a large change. CX Codex +1 753installs security-diff-scan official OpenAI The security-diff-scan skill for Codex reviews pull requests, commits, and patches for security vulnerabilities. It analyzes changed files and related code to identify threats. CX Codex GP ChatGPT +1 30installs diff-context Barnett-Studios diff-context gathers git diffs with surrounding dependency context via cxpak. Useful when reviewing code modifications or drafting pull request summaries. CX Codex +1 ★ 34repo stars diff-computation microsoft The diff-computation rule sets the order for code review: build the diff before reading files. Findings stay on changed lines, and large patches are read in chunks. CX Codex +1 ★ 1,627repo stars

From the same set18

The whole set →
handoff Turns a working session into a short handoff file, so a fresh agent can pick up unfinished work without rebuilding the context. CX Codex +1 ★ 114repo stars squad-review squad-review runs six specialist code reviews on a branch diff, then tests every reported issue with an adversarial verifier. CX Codex +1 ★ 114repo stars socratic-tutor The socratic-tutor skill turns a code review into a guided understanding check, asking about the problem, solution, edge cases, and downstream impact. CX Codex +1 ★ 114repo stars thermo-nuclear-code-quality-review thermo-nuclear-code-quality-review conducts a ruthless maintainability audit on feature branches. Flags tangled logic, oversized files, and opportunities to cut structural bloat. CX Codex ★ 114repo stars code-simplifier code-simplifier refactors complex functions, cuts redundancy, and removes AI slop without touching public APIs or changing runtime behavior. CX Codex ★ 114repo stars git-committer The git-committer subagent reviews repository changes, runs available checks, and creates commits with semantic messages. Use it to hand off the commit workflow to Claude Code. CX Codex ★ 114repo stars tighten-prose tighten-prose strips the habits readers spot as machine-written — word clusters, inflated importance, phantom citations — and rewrites the flagged passages while keeping the author's voice. CX Codex +1 ★ 114repo stars blog-post-writer blog-post-writer converts raw notes, git commits, and logs into a fact-checked, flat blog post draft with explicit author question markers. CX Codex +1 ★ 114repo stars

Project sponsors

Companies that keep this analytics open