explain-diff

Generates self-contained HTML explainers that describe code changes by concept across files.

Updated May 9, 2026
One-click install
npx skills add https://github.com/natelandau/cc-plugin --skill explain-diff-natelandau
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: explain-diff
Source: https://github.com/natelandau/cc-plugin/tree/main/plugins/natelandau-toolkit/skills/explain-diff
Command: npx skills add https://github.com/natelandau/cc-plugin --skill explain-diff-natelandau

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Raw git diffs show which lines changed but not why, making it hard to understand a PR, branch, or commit as a coherent set of features spread across many files. ## Core Features & Use Cases - Concept-level explanation: Identifies the two to five features a change is made of and traces each one across every file and hunk it touches, rather than walking file by file. - Rich HTML output: Produces a single self-contained HTML file with inline CSS, hand-applied syntax highlighting, colored diff hunks, diagrams, and callouts, saved to a gitignored location with a date-prefixed filename. - Flexible diff sources: Resolves the change from a PR number via gh, a branch comparison, a commit range, or the uncommitted working tree. - Use Case: Before merging a teammate's large PR, ask for an explanation and receive a scrolling HTML document with background, intuition, an anatomy of the change, and a code walkthrough organized by concept. ## Quick Start Explain the changes in PR 42 as an HTML document that walks through the concepts and features across all the files it touches.

Frequently Asked Questions about explain-diff

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I get an explanation of a GitHub PR instead of reading the raw diff?

Provide the PR number or URL and the skill fetches the diff with gh pr diff plus the title and description from gh pr view. It then explains the change by concept across files and produces a self-contained HTML explainer.

How do I understand what a branch changes before merging?

The skill diffs the branch against its base, usually main, using git diff base...HEAD. It identifies the two to five features the change consists of and traces each across every file it touches.

Can I get a markdown explanation instead of HTML?

Yes, requesting markdown or a quick terminal-readable output produces a plain .md file instead. The HTML-specific rules for diagrams, syntax highlighting, and styling are skipped in that case.

Where is the generated HTML explanation file saved?

The file is written to .agent/explanations/ inside the repo with a date-prefixed filename, after confirming the path is gitignored via git check-ignore. If no gitignored path exists, it falls back to a temp directory outside the repo.

What happens if I don't specify which change to explain?

The skill defaults to the current branch against main, or the uncommitted working tree if that diff is empty. If the choice is ambiguous it asks; otherwise it picks the sensible default and states which one it chose.