explain-diff · claesbackman — Claude Code skill: what it does, how to install
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.
MIT ★ 579 updated 2026-10-28
npx skills add claesbackman/AI-research-feedback --skill explain-diff -a claude-codeWhat explain-diff does
By default, explain-diff compares the working tree with HEAD; you can also provide a ref or range. It reads changed sections alongside the surrounding code and the files that consume their output. Untracked files count too, and the skill reads each one in full.
The result is a single HTML page with embedded CSS and JavaScript that works offline. It covers the code’s previous behavior, the change, its consequences for results, and a code walkthrough, followed by a five-question quiz. The instructions call for checking output files, images, logs, and numbers directly; a diff alone cannot establish that empirical results changed.
For the Claude Code installation method, run the command below and use the skill file at the listed path. The page is saved outside the repository and records repository, branch, and full SHA details to identify the change it explains. When both the diff and git status --short are empty, there is nothing to analyze.
What it helps with
- explain a code change alongside its surrounding files
- check whether empirical results changed
- include new files that Git has not tracked yet
- create an offline HTML explanation with a quiz
Example prompts for the agent
- Explain the working-tree changes against
HEADand create a page with a quiz. - Compare
main..HEAD, check the consequences for the results, and walk me through the code changes. - Review the diff and new files, then make an offline page for someone who did not write this code.
How to install explain-diff
1Skills CLI (Vercel)
npx skills add claesbackman/AI-research-feedback --skill explain-diff -a claude-code2Manually: put the files in place
~/.claude/skills/explain-diff/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/explain-diff/
1Skills CLI (Vercel)
npx skills add claesbackman/AI-research-feedback --skill explain-diff -a codex2Manually: put the files in place
.agents/skills/explain-diff/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add claesbackman/AI-research-feedback --skill explain-diff -a cursor2Manually: put the files in place
.cursor/skills/explain-diff/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install claesbackman/AI-research-feedback Skills/explain-diff/SKILL.md2Manually: put the files in place
.github/skills/explain-diff/SKILL.md1Skills CLI (Vercel)
npx skills add claesbackman/AI-research-feedback --skill explain-diff -a gemini-cli2Platform CLI
gemini skills install https://github.com/claesbackman/AI-research-feedback --path Skills/explain-diffManually: put the files in place
.devin/skills/explain-diff/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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?
Run npx skills add claesbackman/AI-research-feedback --skill explain-diff -a claude-code. The skill file is at ~/.claude/skills/explain-diff/SKILL.md.
What does explain-diff do?
It reads a diff and the related code, then creates a standalone HTML page explaining the changes and testing comprehension with a quiz. It also examines what changed in the empirical results.
How does explain-diff check whether results changed?
Its instructions call for checking output files, logs, images, and samples rather than inferring effects from code alone. Matching coefficients and observation counts, for instance, can show that an added block had no effect.
Source text
SKILL.md · MIT
--- name: explain-diff description: Explain a code change as a standalone offline HTML page with a five-question quiz. Reads the diff and the surrounding code from scratch, states the consequences for the empirical results, and saves the page outside the repository under a dated filename. argument-hint: "[optional: git ref or range, default working tree vs HEAD]" allowed-tools: Bash, Read, Write, Glob, Grep disable-model-invocation: true --- # Explain a Change Produce one self-contained HTML page that explains a code change well enough that someone who did not write it could defend it, ending in a quiz that tests whether they actually followed. ## Scope Set the target from `$ARGUMENTS`: - No argument — uncommitted working tree against `HEAD`. Use `git status --short` and `git diff` (add `git diff --cached` if anything is staged). - One ref (`abc123`, `main`) — that ref against the working tree, or against `HEAD` if the tree is clean. - A range (`main..HEAD`, `abc123..def456`) — use it as given. **New files are part of the change.** `git diff` shows nothing for an untracked file, so a change that only adds scripts looks empty. Always read `git status --short` for `??` entries and treat every new file as an addition to explain: read it in full, since there is no diff to read. A new robustness script is exactly the kind of change worth explaining, and it is the one the diff will hide. Stop only when `git status --short` and the diff are both empty. ## Read from scratch **Work only from the code and the diff.** If the conversation already contains an account of this change — yours or the user's — ignore it and read the files. A summary written earlier is a hypothesis, not evidence. Do not stop at the diff hunks. For every changed block, read the function, script, or stage that contains it, and read what consumes its output. A three-line addition to a pipeline stage is usually only comprehensible from the two files on either side of it. ## Verify before you claim The single most common failure here is reporting a change in results that did not happen, or missing one that did. Check, do not infer: - **Generated files.** Tables, `.tex` bodies, and rendered figures often show as modified when only a timestamp comment or a nondeterministic tie-break changed. Diff them and look at what actually differs before calling it a result change. - **Binary artifacts.** If an image changed, compare both versions visually. The old version lives in git rather than on disk, so extract it first — `git show HEAD:path/to/figure.png > /tmp/old-figure.png` — then read the extracted copy alongside the working-tree one. A re-render with identical content is not a finding. - **Logs.** Compare sample sizes, observation counts, and headline coefficients between the old and new run. Identical numbers are the proof that an added block was inert; do not assert it from code reading alone. - **Numbers you quote.** Every figure in the page should come from an output file you opened, not from the prose of the diff. If the change writes a new CSV, read it. - **Samples.** When a new block filters data, compare its filter line by line against the filters of the existing estimation samples. Differences of one clause are the interesting ones. ## Sections Write these five, in order, under clear headings. **1. What this code did before.** Explore the surrounding scripts. Do not rely on the diff alone. Establish what the code produced, what consumed it, and — where it matters — what it conspicuously did not produce. **2. What changed and why, in plain language.** No code in this section at all. Prose only. Name the problem the change solves before describing the solution. **3. Consequences for the results.** Which sample, which coefficients, which tables, and in which direction. Be specific about magnitudes. If the answer is that nothing changed, **say so explicitly and prominently**, then show the evidence — matching observation counts, matching coefficients, timestamp-only diffs. A reader must not have to infer "no effect" from the absence of a claim. Where a change adds something rather than altering something, say what is new and what sample it rests on. **4. Walkthrough of the changed code, grouped by purpose rather than by file.** One group per job the change does, even when a single job spans two files. Quote the code in `<pre>` blocks with the file and line range above each. Explain the lines that are load-bearing and skip the ones that are not, and say why a line is there when the reason is not obvious from reading it. **5. Quiz.** Five multiple-choice questions, medium difficulty — hard enough that answering requires understanding the substance, not gotchas. ## Quiz rules - **At least two questions must be about empirical consequences** rather than syntax: which observations enter the sample, what the coefficient now identifies, what would change if an assumption failed, whether a modified output file means the results moved. - Distractors must be plausible misunderstandings — the reading someone would arrive at from a careless pass over the diff. Match the correct answer in length, grammar, specificity, and confidence. A correct answer that is visibly longer or more hedged than its distractors is a giveaway. - **Randomise the position of the correct answer independently for each question.** Do not settle into a pattern. - On click: report whether the answer was correct, then explain **every** option — why the right one is right and why each wrong one is wrong. The wrong-answer explanations carry most of the teaching. - Cite the file and line each answer rests on, below the explanation. ## Page Single HTML file. **Embed all CSS and JavaScript** so it works offline with no network access. - Clear prose. Full sentences, not bullet fragments, wherever the content allows. - Concrete toy examples with made-up small numbers — a four-row table showing what a reshape or a merge does beats a paragraph describing it. - Simple HTML/CSS diagrams rather than ASCII art: flex-box pipeline boxes, positioned dots and bars for a chart, styled tables for data. - Code in `<pre>` tags, with the file path and line range in a small monospace label above. - Support light and dark via `prefers-color-scheme`. - Real tables for tabular data, wrapped in an `overflow-x: auto` container. ## Provenance Pages accumulate. Six months on, the only thing that makes one worth keeping is knowing exactly which change it describes, so record that in the page itself rather than trusting the filename. Directly under the page title, a small block giving: - Repository name, from `git rev-parse --show-toplevel`. - Branch, from `git rev-parse --abbrev-ref HEAD`. - The comparison, spelled out as the git command you actually ran — `git diff` against `HEAD`, `git diff abc123`, `main..HEAD`. - The **full 40-character SHA** of each endpoint, from `git rev-parse`. Short SHAs collide as a repository grows; the page is the archival record, so it carries the full one. - The date the page was written. When the comparison involves the working tree, say so explicitly and add the list of changed and new files. An uncommitted tree is not reproducible — the state this page describes may never exist again, and a reader who later checks out the recorded SHA will not see it. That caveat belongs on the page. ## Output Save **outside the repository**. Default directory `~/Documents/`; use a different one if the user names it. Confirm with `git status` afterwards that the repo is untouched. Filename: today's date in `YYYY-MM-DD-` format, a short kebab-case slug of the change, then a ref tag so the file can be matched back to a commit without opening it. - Working tree against `HEAD` — `wt-` plus the short SHA of `HEAD`, as in `2026-08-01-cluster-by-municipality-wt-e956a7e.html`. - One ref — its short SHA. - A range — both short SHAs joined by a hyphen, as in `a1b2c3d-def4567`. Then tell the user the path, and follow it with a short plain-text summary of what you found — the same conclusions the page reaches, including anything you noticed while reading that the change's author might want to know. Do not make the user open the file to learn whether the results moved.
© claesbackman · MIT · claesbackman/AI-research-feedback
Similar skills
All skills for Code review and refactoring →explain-diff by other authors comes first.