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

83%

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/agentic-sdlc

SKILL.md
Quality
Evals
Security

Quality

Content

71%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.

The body is a well-organized, largely actionable specification with genuine security discipline (per-sink escaping, CSP, redaction, untrusted-content framing) and an explicit pre-save validation scan. Its main defects are a dangling MICROWORLDS.md reference, some motivational/explanatory padding, and directional rather than concrete guidance for diagrams and the merge-base lookup.

Suggestions

Ship the missing MICROWORLDS.md bundle file (or inline its essentials into SKILL.md) — the body's only bundle reference, [MICROWORLDS.md](./MICROWORLDS.md), currently points to a file that does not exist, so the delegation fails at runtime.

Tighten conciseness by trimming the cognitive-debt preamble and the Kleppmann style note, and dropping rationale Claude can infer (e.g., the explanation of why a missing white-space: pre-wrap collapses newlines).

Make the diagram and merge-base guidance concrete: give one reusable HTML/CSS diagram skeleton as a starter pattern and the exact merge-base command, so the Format and Scope sections are executable rather than descriptive.

DimensionReasoningScore

Conciseness

The body is dense with skill-specific guidance (per-sink escaping rules, exact CSP values, filename patterns, quiz randomization) and mostly assumes Claude's competence, matching 'efficient; minor instances of over-explanation'. It slips below the 5 anchor via the motivational cognitive-debt preamble, the Kleppmann style note, and rationale Claude can infer (e.g., why missing white-space: pre-wrap collapses newlines).

4 / 5

Actionability

Mostly executable guidance: exact commands ("git fetch origin", "<merge-base>..HEAD"), a copy-pasteable CSP directive ("object-src 'none'; base-uri 'none'; form-action 'none'"), concrete temp-file naming with slug charset, and precise per-sink escaping rules. It falls short of fully copy-paste-ready because the merge-base lookup and diagram construction are described directionally rather than given as concrete patterns — the 4 anchor, not the 5.

4 / 5

Workflow Clarity

A clear sequence is present (resolve target → explore surrounding code → build the four sections in order → apply format rules → pre-save scan → write outside the repo → report the path) with 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" and "Extend the pre-save scan to cover both sinks". It misses the 5 anchor because there is no error-recovery feedback loop (what to do when the scan fails) and the workflow is laid out as a spec rather than an explicitly ordered procedure.

4 / 5

Progressive Disclosure

In-file structure is good (Scope / Sections / Format / never-does headers) and the micro-worlds catalog is correctly delegated to a clearly signaled one-level reference, "[MICROWORLDS.md](./MICROWORLDS.md)" — but that file does not exist in the bundle (the bundle contains only SKILL.md), so the single progressive-disclosure reference dangles and navigation fails exactly where content splitting is attempted. Structure is present, but the reference layer is broken, fitting 'some structure but could be better organized' better than the 4 anchor.

3 / 5

Total

15

/

20

Passed

Description

88%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: third-person, concrete about the deliverable and its sections, with an explicit and multi-trigger 'Use when' clause. The only weaknesses are a few missing natural trigger phrasings and slight overlap risk with review-oriented skills via the 'before reviewing or merging' wording.

DimensionReasoningScore

Specificity

"Produce a rich, interactive, self-contained HTML explanation of a code change — background, intuition with diagrams, a code walkthrough, and a comprehension quiz" enumerates multiple concrete deliverable components (background, diagrammed intuition, walkthrough, interactive quiz) plus the exact output format (self-contained HTML). Coverage of what the skill produces is comprehensive, matching the top anchor rather than the 'minor gaps' level below it.

5 / 5

Completeness

Both halves are explicit: a clear 'what' (self-contained interactive HTML explanation with four named sections) and a concrete 'Use when' clause listing diff, branch, commit range, PR, pre-review/pre-merge understanding, and cognitive-debt paydown. This clearly matches the anchor 'clearly and explicitly answers both what AND when with concrete trigger phrases', not the 4 anchor where 'when' could be more specific.

5 / 5

Trigger Term Quality

Natural trigger terms are well covered: "explain a diff, branch, commit range, or PR", "wants to understand a change before reviewing or merging it". A few natural phrasings users would say are missing (e.g., "walk me through this change", "what does this PR do"), so it sits at good-but-not-comprehensive coverage rather than the 5 anchor.

4 / 5

Distinctiveness Conflict Risk

The niche (HTML explanations of code changes) is distinct and the primary triggers ("explain a diff/PR") are unambiguous. Minor overlap risk remains with a code-review skill because the trigger clause mentions wanting to understand a change "before reviewing or merging it", which could fire in review contexts — mostly distinct with minor overlap, the 4 anchor.

4 / 5

Total

18

/

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/ai-report-platform

Path

.agents/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.