explain-changes

Explain how the code on the current branch works, as an HTML page opened in the browser, written so someone can understand the change and review it. Use when asked to explain a branch, explain these changes, walk me through this code, help me review this, or explain what an agent just did. Most useful when someone other than the reader wrote the code and it has to be understood before merging.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, opinionated instruction skill with concrete commands, a clear sequenced workflow, and a single properly externalized template reference. It is held back only by some discursive framing prose and the inherently non-executable nature of the core writing guidance.

Suggestions

Tighten the opening two paragraphs: the philosophical framing about reviewing-vs-understanding and the 'Do not fix anything' paragraph could be condensed to direct instructions without losing the key constraint.

Add an explicit final verification step such as confirming the written HTML file exists and opened successfully before printing the path, to close the small validation gap.

Consider showing one minimal inline HTML skeleton derived from page-template.html so the structural contract (code block classes, mermaid pre, cols div) is visible without requiring the reader to open the reference.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence without explaining basic concepts, but the opening framing ('Those two things are not separate. Nobody can review code they do not understand...') and 'Do not fix anything...' paragraph contain rhetorical padding that could be trimmed.	4 / 5
Actionability	It supplies copy-paste-ready git commands, a concrete permalink format, a concrete output path, and points to a real template file; the central explanation-writing task is instruction-based (appropriate for the skill type) with minor gaps.	4 / 5
Workflow Clarity	Sections (Scope, Read beyond the diff, How to write it, Link to the code, Output) form a clear sequence with a verification checkpoint ('Never emit a link you have not confirmed resolves to a pushed commit'), leaving only minor validation gaps.	4 / 5
Progressive Disclosure	The body is a clear overview with section headers and a single well-signaled one-level-deep reference to references/page-template.html (verified present), which appropriately externalizes the HTML/styling bulk.	5 / 5
	Total	17 / 20 Passed

Description

95%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that clearly states what the skill does and when to use it, with natural trigger phrasing and a distinct niche. The only slight gap is that the core verb 'explain' is somewhat abstract compared to the most action-rich anchor.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions ('Explain how the code on the current branch works, as an HTML page opened in the browser') rather than vague language, with only minor gaps versus the comprehensive-coverage anchor.	4 / 5
Completeness	It explicitly answers both what ('Explain how the code on the current branch works, as an HTML page opened in the browser') and when ('Use when asked to explain a branch...'), with concrete trigger phrases.	5 / 5
Trigger Term Quality	It provides comprehensive natural phrases users actually say ('explain a branch', 'walk me through this code', 'help me review this', 'explain what an agent just did'), including synonym variations of explain/review.	5 / 5
Distinctiveness Conflict Risk	The branch-explanation-as-HTML-review-page niche is distinct, and triggers like 'explain what an agent just did' and 'walk me through this code' carry minimal overlap risk with adjacent code-review skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: freekmurze/dotfiles
Path: config/claude/skills/explain-changes/SKILL.md
Commit: 50345d3

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.