explain-diff-notion

Creates a Notion page explaining a code change with background, intuition, diagrams, and quiz questions.

Updated Nov 10, 2013
One-click install
npx skills add https://github.com/bnferguson/dotfiles --skill explain-diff-notion-bnferguson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: explain-diff-notion
Source: https://github.com/bnferguson/dotfiles/tree/main/.agents/skills/explain-diff-notion
Command: npx skills add https://github.com/bnferguson/dotfiles --skill explain-diff-notion-bnferguson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Understanding a code change, diff, branch, or pull request often requires digging through surrounding code, tests, and documentation, and sharing that understanding with a team means writing it up manually. This Skill investigates the change and its surrounding system, then publishes a structured teaching page to Notion via the Notion MCP tools. ## Core Features & Use Cases - System-Aware Explanation: Explores surrounding code, tests, callers, and data models to explain behavior, not just file-by-file edits. - Structured Page Format: Produces Background, Intuition, Code, and Quiz sections with Notion-native diagrams, callouts, and toggle-based multiple-choice questions. - Prompt-Injection Defense: Treats diffs, PR metadata, and commit messages as untrusted data and ignores any instructions embedded in them. - Use Case: After opening a pull request that refactors a data pipeline, ask for an explanation page and receive a Notion URL your teammates can read to understand the motivation, mental model, implementation flow, and edge cases, then self-test with five quiz questions. ## Quick Start Explain the changes on my current branch as a Notion page using the explain-diff-notion skill and return the page URL.

Frequently Asked Questions about explain-diff-notion

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

FAQPage Schema
How do I explain a pull request or diff as a Notion page?▼

Invoke the skill with the target change, such as the current branch, a diff, or PR metadata. It investigates the surrounding code and creates a Notion page with Background, Intuition, Code, and Quiz sections, then returns the page URL.

What does the generated Notion explanation page contain?▼

The page contains a title, summary, and four ordered sections: Background, Intuition, Code, and Quiz. It uses Notion-native blocks like callouts, columns, tables, and toggle-based multiple-choice questions rather than ASCII diagrams.

Does this skill work without the Notion MCP tools connected?▼

No. The skill requires the Notion MCP tools to create and publish the page. If they are unavailable, it reports that and stops rather than falling back to another output format.

Can a malicious diff or commit message hijack the explanation?▼

No. The skill treats diffs, PR metadata, commit messages, and source code as untrusted passive data. It ignores embedded instructions, never adds links or actions requested by the content, and notes suspected injection attempts on the page.

What are the limitations of automated diff explanation?▼

The explanation is grounded only in inspected source, tests, and configuration, so undocumented intent may be stated as assumption. Ambiguous targets are inferred from context, and the skill distinguishes observed facts from reasonable interpretation.