# diff-skill

Diffs two revisions of a skill's markdown instructions and flags the edits that weaken a rule or add avoidable complexity. Useful before you accept changes to a skill you rely on.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 155 repo stars
- Author: serpro69
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/serpro69/claude-toolbox/tree/HEAD/kodex-plugin/skills/diff-skill/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/diff-skill

## What it does

Point it at a skill and it compares the markdown that drives that skill across two revisions. The check runs one way: a dropped requirement, a softened rule, a missing verification step or a broken link counts as a regression, while fresh clarifications and extra examples do not. Content that moved but survived the edit stays neutral. Complexity is split too: what the edit introduced affects the verdict, and older issues are listed separately as suggestions.

By default it diffs `HEAD` against the working tree, and you can name other refs in the prompt. Starting from `SKILL.md` it follows the markdown links and covers every file it can reach, so a rule buried in a reference file still gets compared. Output lands in `docs/reviews/diff-skill/<slug>-<sha-a>-<sha-b>.md`, plus a short inline summary with the verdict, the finding counts and the path.

The shortcut `$kk:diff-skill <skill-name>` resolves `klaude-plugin/skills/<skill-name>/SKILL.md`, and asks you for the directory when that file is missing. Phases are strictly ordered: the skill reads its own `diff-process.md` first and won't touch the target before that. Findings get indexed in the capy knowledge base under `kk:review-findings`, but only when there is something to report.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill diff-skill -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/diff-skill/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/diff-skill/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill diff-skill -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/diff-skill/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill diff-skill -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/diff-skill/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install serpro69/claude-toolbox kodex-plugin/skills/diff-skill
```

2. **Manually: put the files in place**
- File: `.github/skills/diff-skill/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill diff-skill -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/serpro69/claude-toolbox --path kodex-plugin/skills/diff-skill
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/diff-skill/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/serpro69/claude-toolbox/tree/HEAD/kodex-plugin/skills/diff-skill/SKILL.md

## When to use it
- catch a requirement that vanished during an instruction rewrite
- tell a weakened constraint apart from a harmless clarification
- review every linked file a skill pulls in, not just `SKILL.md`
- keep older complexity issues from sinking the verdict on a new edit
- get a written report with the path and the number of findings

## Example prompts
- Diff the `deploy-guard` skill against its last commit and list anything that got weaker
- Run `$kk:diff-skill commit-style` and tell me whether the edit introduced a regression
- Compare `HEAD~2` with the working tree for the `release-check` skill

## Similar
- [understand-diff](https://affpapa.org/en/nevibecode/skills/understand-diff.md) — skill · 4200 installs
- [diff-context](https://affpapa.org/en/nevibecode/skills/diff-context.md) — skill · ★ 34 repo stars
- [diff-analyze](https://affpapa.org/en/nevibecode/skills/diff-analyze.md) — skill · 753 installs
- [diff-computation](https://affpapa.org/en/nevibecode/rules/diff-computation.md) — rule · ★ 1627 repo stars
- [tasks-explain-diff](https://affpapa.org/en/nevibecode/skills/tasks-explain-diff.md) — skill · ★ 40 repo stars
- [diff-scanning-with-aws-security-agent](https://affpapa.org/en/nevibecode/skills/diff-scanning-with-aws-security-agent.md) — skill · 1600 installs

From the same set: [serpro69/claude-toolbox](https://affpapa.org/en/nevibecode/by/serpro69/claude-toolbox.md) — 30 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
