CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

explain-diff

Produce a rich, interactive, self-contained HTML explanation of a code change — background, intuition with diagrams, a code walkthrough, and a comprehension quiz. Use when the user asks to explain a diff, branch, commit range, or PR, wants to understand a change before reviewing or merging it, or wants to pay down cognitive debt on code an agent wrote.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is explain-diff in agranado2k/google-books-clojure

SKILL.md
Quality
Evals
Security

Quality

Content

75%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-crafted instruction-only skill: concrete deliverable specs, real security engineering (per-sink escaping, CSP, secret redaction, prompt-injection distrust of diff content), and an explicit pre-save validation scan. The consistent weaknesses are minor — no literal commands for the merge-base resolution, sequence spread across sections instead of one procedure, a few trimmable rationale asides, and a referenced MICROWORLDS.md that is missing from the bundle.

Suggestions

Include the actual git commands for scope resolution (e.g., `git merge-base origin/<default> HEAD` then `git diff <merge-base>..HEAD`) so the targeting step is copy-paste executable rather than described.

Ship the referenced MICROWORLDS.md alongside SKILL.md (or inline its essential heuristics) — the body delegates the microworld catalog, honesty rules, and when-to-use guidance to a file that is not present in the bundle.

Consolidate the operating procedure into one ordered list (resolve change → explore background → write sections → apply format/escaping rules → pre-save scan → report path), making the pre-save scan an explicit pass/fail gate with a fix-and-rescan loop.

DimensionReasoningScore

Conciseness

The body is dense and instructional — scope resolution, section specs, format/security rules — with almost no padding of concepts Claude already knows. Minor over-explanation could be trimmed: the rationale asides ("a quiz whose right answer is always option B tests pattern-matching", "or the browser will collapse all newlines"), the Kleppmann style flourish, and the three-line provenance footer, which keeps it below the lean anchor 5 but above the noticeably-verbose anchors.

4 / 5

Actionability

For an instruction-only skill the guidance is highly concrete: literal "git fetch origin", a fully specified output path scheme with an example ($TMPDIR/YYYY-MM-DD-explanation-<slug>.html, slug charset), exact CSP directives, per-sink escaping rules, and a precise quiz spec (five questions, randomized correct-answer position, click feedback). It stops short of anchor 5's copy-paste readiness — the merge-base step says "find the merge-base" without the literal `git merge-base` command, and default-branch detection is delegated to a constitution file.

4 / 5

Workflow Clarity

The flow — resolve the change, explore surrounding code for background, write the four sections, apply format rules, run the pre-save scan, report the path — is coherent and includes an explicit validation checkpoint ("Before saving the file, scan each code block in the HTML source and confirm its CSS includes white-space: pre or pre-wrap", extended to both sinks). It is not a 5: the sequence is distributed across sections rather than one ordered procedure, and there is no error-recovery loop for what to do when the pre-save scan fails; it is above anchor 3 because the checkpoint is explicit, not implicit.

4 / 5

Progressive Disclosure

Good in-file structure (Scope, Sections, Format, boundaries) with a single, well-signaled one-level reference: MICROWORLDS.md is pointed to with a precise description of what it carries ("catalog of world types, the when-to-use heuristics, and the honesty rules"). The gap keeping it from 5: that referenced file is not present in the skill bundle — no references/, scripts/, or assets/ directories exist and no MICROWORLDS.md sits alongside SKILL.md — so the sole external navigation point is a dead link, though it degrades gracefully since the micro-world feature is optional and conditional.

4 / 5

Total

16

/

20

Passed

Description

92%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 description: it states a concrete, distinctive deliverable and gives an explicit, well-phrased "Use when" clause covering diff, branch, commit range, and PR triggers. The only gap is that a few natural synonyms ("walk through", "what does this change do") are absent.

DimensionReasoningScore

Specificity

The description enumerates the concrete deliverable and its full composition: "Produce a rich, interactive, self-contained HTML explanation of a code change — background, intuition with diagrams, a code walkthrough, and a comprehension quiz." Multiple specific actions with comprehensive coverage of the output, matching the anchor-5 example's breadth; it is not merely a domain label with 1-2 actions (anchor 3) nor missing coverage (anchor 4).

5 / 5

Completeness

Both halves are explicit: the "what" is the self-contained interactive HTML explanation with its four named parts, and the "when" opens with "Use when the user asks to explain a diff, branch, commit range, or PR..." with concrete trigger phrases. This mirrors the anchor-5 example structure exactly; anchor 4 would require the when-clause to be less explicit, which it is not.

5 / 5

Trigger Term Quality

Natural trigger phrases are present — "explain a diff, branch, commit range, or PR", "wants to understand a change before reviewing or merging it" — which users would plausibly say. A few common variations are missing (e.g., "walk me through this change", "what does this PR do", "how does this work"), so it lands at good-but-not-comprehensive coverage rather than anchor 5.

4 / 5

Distinctiveness Conflict Risk

A clear niche: an interactive teaching artifact (with quiz) for code changes, explicitly positioned before review/merge decisions rather than as a review itself. Triggers ("explain", "understand a change") are distinct from review-skill phrasing, and the unique deliverable minimizes conflict risk, matching anchor 5 rather than the minor-overlap anchor 4.

5 / 5

Total

19

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 1 possibly missing (./MICROWORLDS.md)

Warning

Total

15

/

16

Passed

Repository

agranado2k/tic-tac-toe-with-agentic-sdlc

Path

.claude/skills/explain-diff/SKILL.md

Reviewed

Table of Contents

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.