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

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, highly actionable instruction set for a generative task, with unusual strength in security details (per-sink escaping, CSP, secret redaction) and an explicit pre-save validation scan. Its main defects are a missing bundle file (MICROWORLDS.md is referenced but absent), an implied rather than explicit step sequence, and a few trimmable editorial asides.

Suggestions

Ship MICROWORLDS.md in the skill bundle (or inline its essentials and drop the link) — the body delegates the microworld catalog, heuristics, and honesty rules to a file that does not exist, so that guidance is currently unreachable.

Give the exact target-resolution commands (e.g., `git merge-base origin/<default> HEAD` and the `<merge-base>..HEAD` range syntax) instead of describing the merge-base lookup procedurally.

Trim the justificatory asides (e.g., the pattern-matching quiz rationale and the reader-trust paragraph) to pure directives to tighten token efficiency.

DimensionReasoningScore

Conciseness

The body is dense with non-obvious, load-bearing rules (per-sink escaping, CSP directive, temp-file naming scheme, quiz answer randomization) and assumes Claude's competence, but editorial asides like "a quiz whose right answer is always option B tests pattern-matching, not understanding" and the trust/agenda rationale are padding that could be trimmed. Mostly lean with minor over-explanation, fitting the level-4 anchor rather than the fully lean level-5 anchor.

4 / 5

Actionability

Guidance is highly concrete for an instruction-only skill: exact CSS requirements ("white-space: pre-wrap"), a verbatim CSP policy ("object-src 'none'; base-uri 'none'; form-action 'none'"), a file-naming example ("$TMPDIR/2026-01-12-explanation-<slug>.html") with a slug charset, and a five-question medium-difficulty quiz spec. Minor gaps keep it from level 5: the merge-base resolution is described rather than given as an exact command, and the default branch name is delegated to an external constitution file.

4 / 5

Workflow Clarity

The sequence (resolve target, explore surrounding code, write the four sections, escape per sink, run the pre-save scan, write outside the repo, 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" with the scan extended to both sinks. It is not level 5 because the phases must be assembled from topic sections rather than an explicit ordered workflow with feedback loops.

4 / 5

Progressive Disclosure

In-file structure is good (clear Scope / Sections / Format / non-goals headers, appropriate length), and the one external reference is clearly signaled and described ("[MICROWORLDS.md](./MICROWORLDS.md) carries the catalog of world types, the when-to-use heuristics, and the honesty rules"). However, no bundle directories or MICROWORLDS.md exist alongside SKILL.md, so the skill's sole referenced file is missing and its navigation target is unavailable — a real organizational gap that drops it below level 4.

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: it explicitly states both what the skill produces and when to use it, with natural trigger terms and a clearly differentiated teach-don't-review niche. The only weaknesses are a few missing natural trigger synonyms and slight adjacency to code-review triggers via the "before reviewing or merging" phrasing.

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" names the deliverable plus four concrete components, comprehensively covering what the skill outputs. Coverage is complete rather than having minor gaps, so it fits the level-5 anchor better than level 4.

5 / 5

Completeness

The first sentence explicitly answers "what" (self-contained HTML explanation with background, intuition, walkthrough, quiz) and "Use when the user asks to explain a diff, branch, commit range, or PR..." explicitly answers "when" with concrete trigger phrases. This mirrors the level-5 anchor example; the when-clause is fully explicit, not merely present.

5 / 5

Trigger Term Quality

"explain a diff, branch, commit range, or PR" and "wants to understand a change before reviewing or merging it" are natural phrases users would say, giving good keyword coverage. A few natural variations (e.g., "walk me through this change", "what does this PR do") are missing, so it does not reach comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The explain/teach niche (interactive HTML explanation with a quiz) is clearly distinct from review or fix skills, and triggers like "explain a diff" are unambiguous. However, "before reviewing or merging it" sits adjacent to code-review skill triggers, creating minor overlap risk with a closely related skill, which matches the level-4 anchor better than level 5.

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/tic-tac-toe-haskell

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.