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

91%

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

SKILL.md
Quality
Evals
Security

Quality

Content

82%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 strong, highly actionable instruction skill: concrete commands, an exact output-file convention, explicit security controls (per-sink escaping, CSP, secret redaction), and a pre-save verification scan. The main weaknesses are motivational prose that could be trimmed, a workflow distributed across sections rather than sequenced end-to-end, and a referenced MICROWORLDS.md file that does not exist in the bundle.

Suggestions

Trim the motivational passages (the cognitive-debt framing paragraphs, the quiz-discipline rationale, and the 'destroys the reader's trust' sentence) down to their operative directives, and shorten or drop the provenance footer.

Present the pipeline once as an explicit ordered sequence — resolve target, explore background, draft the four sections, run the pre-save scan, write to the temp path, report the path — including a fix-and-rescan loop if the scan finds an unescaped sink.

Ship MICROWORLDS.md alongside SKILL.md (e.g., under references/ with the link updated) so the catalog the body relies on actually resolves, or inline the minimal when-to-use heuristics and drop the reference.

DimensionReasoningScore

Conciseness

The body is dense with skill-specific directives and avoids explaining concepts Claude already knows, but includes motivational prose that could be trimmed — 'Failing your own quiz is the cheapest possible signal that the change outran your understanding', 'a teaching pass that quietly turns into a review destroys the reader's trust', the cognitive-debt framing paragraphs, and the six-line provenance footer — matching 'minor instances of over-explanation'.

4 / 5

Actionability

The guidance is fully executable: concrete git procedure ('git fetch origin', merge-base resolution, '<merge-base>..HEAD'), an exact output path convention ('$TMPDIR/<YYYY-MM-DD>-explanation-<slug>.html' with the slug constrained to '[a-z0-9-]'), a copy-pasteable CSP directive, explicit CSS rules ('white-space: pre-wrap'), per-sink escaping rules, and a defined quiz structure (five questions, randomized correct-answer position).

5 / 5

Workflow Clarity

The section order is explicit ('The explanation has these sections, in this order') and there is a genuine pre-save validation checkpoint ('scan each code block in the HTML source and confirm its CSS includes white-space: pre or pre-wrap', extended to both escaping sinks), but the pipeline is distributed across Scope/Sections/Format sections rather than given as one ordered sequence, and no fix-and-rescan recovery loop is specified — 'clear sequence with most checkpoints present; minor validation gaps'.

4 / 5

Progressive Disclosure

The body is well-sectioned with a clearly signaled one-level-deep reference ('[MICROWORLDS.md](./MICROWORLDS.md) carries the catalog of world types, the when-to-use heuristics, and the honesty rules'), but that referenced file is not present in the skill bundle — a minor organization gap against the 'appropriately split, easy navigation' anchor.

4 / 5

Total

17

/

20

Passed

Description

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

The description is exemplary: it states a concrete, multi-part deliverable in third person, provides an explicit 'Use when...' clause with natural trigger phrasings and synonyms, and carves out a distinctive non-review niche. It hits the score-5 anchor on every dimension with no padding or over-claims.

DimensionReasoningScore

Specificity

The description names the concrete deliverable ('rich, interactive, self-contained HTML explanation') and enumerates its four components — 'background, intuition with diagrams, a code walkthrough, and a comprehension quiz' — giving comprehensive, specific coverage of what the skill produces rather than vague domain language.

5 / 5

Completeness

It explicitly answers both halves: the 'what' is a self-contained HTML explanation with named sections, and an explicit 'Use when...' clause lists concrete trigger scenarios (explain a diff/branch/commit range/PR, understand before reviewing or merging, code an agent wrote) — exactly the score-5 anchor pattern.

5 / 5

Trigger Term Quality

Natural user phrasings are well covered with synonyms — 'explain a diff, branch, commit range, or PR', 'wants to understand a change before reviewing or merging it' — matching how a user would actually ask for this; 'cognitive debt on code an agent wrote' additionally captures a distinctive real trigger.

5 / 5

Distinctiveness Conflict Risk

A teaching-only interactive HTML explainer for code changes is a clear niche with distinct triggers; it is explicitly non-review ('it never judges, comments, or fixes' in the body), so overlap with review or general-explanation skills is minimal.

5 / 5

Total

20

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

metadata_version

'metadata.version' is missing

Warning

relative_links

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

Warning

Total

13

/

16

Passed

Repository

agranado2k/agentic-sdlc

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.