skill-diff

Overview

skill-diff generates side-by-side HTML diffs for changed SKILL.md files to help review skill changes. It organizes results by scope and auto-opens in a browser for quick verification, ensuring changes are intentional before merging.

How This Skill Works

The Node script compares the before/after content of changed SKILL.md files and renders a visual HTML diff. It exposes three scopes—Uncommitted (working tree vs HEAD), Staged (index vs HEAD), and Branch (HEAD vs main)—so you can isolate and review different types of changes, with the result automatically opened in your browser.

When to Use It

• Before committing changes to a skill to verify what was added or removed
• When reviewing changes across a feature branch vs main
• To inspect uncommitted changes in your working tree
• During code or content review sessions to focus on diffs by scope
• Prior to merging to ensure only intended skill changes are included

Quick Start

1. Step 1: Run the diff script: node .claude/skills/skill-diff/scripts/skill-diff.js
2. Step 2: Let the tool auto-open the HTML diff in your browser
3. Step 3: Review Uncommitted, Staged, and Branch diffs to verify changes

Best Practices

• Run the diff before creating a pull request to catch unintended edits
• Review both the before and after views to understand the impact
• Use scope filters (Uncommitted, Staged, Branch) to focus on relevant changes
• Let the script auto-open the HTML diff to avoid manual steps
• Verify that HTML diffs render correctly in the browser and document any fixes

Example Use Cases

• A developer checks a skill-edit feature branch to confirm the SKILL.md changes align with the commit message
• A maintainer reviews a PR by comparing HEAD vs main to ensure no accidental deletions
• QA compares working tree diffs to ensure documentation updates match code changes
• Content editors validate that edits in SKILL.md are correctly reflected before release
• Team uses the tool to prepare diffs for a knowledge-base update in a sprint

Frequently Asked Questions