diff-skill skill
Compares two versions of skill instructions to detect instruction degradations and complexity regressions.
- GitHub stars
- 155
- Files
- 14
- Last commit
- Nov 10, 2026
- License
- —
- Allowed tools
- —
What does the diff-skill skill do?
diff-skill compares two versions of skill instructions to detect instruction degradations and complexity regressions.
Summary generated from the skill's SKILL.md.
About the diff-skill skill
Developers reviewing changes to skill instructions can use this tool to identify instruction degradations or complexity regressions. It functions as an asymmetric check, meaning it ignores beneficial additions or clarifications and focuses solely on negative changes like dropped constraints, weakened verification steps, or broken references. An agent should load this skill when a user requests to diff, compare, or review changes to a skill's markdown instructions.
The tool compares the HEAD version against the working tree by default, walking the full reachable file set through markdown links starting from the SKILL.md file. It produces a detailed report file located in docs/reviews/diff-skill/ and provides an inline summary containing the verdict and finding counts. If the tool detects any degradations or complexity regressions, it indexes the findings under kk:review-findings. It relies on the diff-process.md file to guide its sequential execution phases.
What an agent can do with it
- 1Detect instruction degradationCheck if an edit to a skill's markdown instructions accidentally removed a load-bearing instruction or weakened a constraint.
- 2Identify complexity regressionsDetermine if recent changes have made a skill more difficult for a large language model to follow.
- 3Generate automated review reportsCreate a markdown report documenting the differences between two versions of a skill's documentation.
- 4Audit skill instruction changesReview the differences between the current HEAD and the working tree for a specific skill.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the diff-skill skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the diff-skill skill in Plugin
/plugin marketplace add serpro69/claude-toolbox /plugin install kk@claude-toolbox
Install the diff-skill skill in Claude Code
~/.claude/skills/diff-skill/SKILL.md
$ npx degit serpro69/claude-toolbox/klaude-plugin/skills/diff-skill ~/.claude/skills/diff-skillInstall the diff-skill skill in Claude Code (project)
.claude/skills/diff-skill/SKILL.md
$ npx degit serpro69/claude-toolbox/klaude-plugin/skills/diff-skill .claude/skills/diff-skillInstall the diff-skill skill in Codex
~/.agents/skills/diff-skill/SKILL.md
$ npx degit serpro69/claude-toolbox/klaude-plugin/skills/diff-skill ~/.agents/skills/diff-skillInstall the diff-skill skill in Gemini CLI
~/.gemini/skills/diff-skill/SKILL.md
$ npx degit serpro69/claude-toolbox/klaude-plugin/skills/diff-skill ~/.gemini/skills/diff-skillInstall the diff-skill skill in Claude.ai
npx degit serpro69/claude-toolbox/klaude-plugin/skills/diff-skill diff-skill && zip -r diff-skill.zip diff-skill # claude.ai → Customize → Skills → + → Create skill → Upload a skill → diff-skill.zip
SKILL.md
View on GitHubDiff Skill Instructions
Goal: Detect whether an edit to a skill's markdown instructions introduced degradations or made the skill harder for an LLM to follow.
Two judgment axes:
- Degradation (asymmetric) — load-bearing instruction dropped, constraint weakened, verification step removed, scope narrowed, required output dropped, or reference broken. Content relocated but preserved is neutral.
- Complexity — split into regressions (introduced or worsened by the edit, affects verdict) and pre-existing advisories (exist regardless of the edit, surfaced as improvement opportunities, does NOT affect verdict).
Conventions
- Read capy knowledge base conventions at shared-capy-knowledge-protocol.md.
Required Outputs
- Report written to
docs/reviews/diff-skill/<slug>-<sha-a>-<sha-b>.md - Inline summary presented (under 10 lines: verdict, finding counts, report path)
- Capy indexed under
kk:review-findingsif any degradation or complexity regression findings exist (skip on clean results and pre-existing advisories)
Invocation
/kk:diff-skill <skill-name>
Convenience shortcut: resolves klaude-plugin/skills/<skill-name>/SKILL.md. If not found, asks the user for the skill directory path.
Defaults: HEAD (before) → working tree (after). User can specify different refs in the prompt.
Workflow
Mandatory order — load instructions before acting on subject matter. The phases below are strictly sequential. Do not read skill content, build file sets, or produce judgments until you have loaded and internalized the full process file. The only early contact with the target skill is its name and SKILL.md path — enough to validate, not enough to judge.
See diff-process.md for the detailed step-by-step process.
Files in this skill
14diff-skill skill questions
How do I install the diff-skill skill in Claude Code?
Run npx degit serpro69/claude-toolbox/klaude-plugin/skills/diff-skill ~/.claude/skills/diff-skill. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the diff-skill skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What does the skill consider a degradation?
A degradation is defined as a dropped load-bearing instruction, a weakened constraint, a removed verification step, a narrowed scope, a dropped required output, or a broken reference.
How are additions and clarifications treated during a comparison?
Additions, clarifications, and strengthenings are not considered degradations.
Where is the comparison report saved?
The report is written to the docs/reviews/diff-skill/ directory.