code-documentation-code-explain

You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable explanations.

Quality

55%

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

Fix and improve this skill with Tessl

tessl review fix ./.agent/skills/code-documentation-code-explain/SKILL.md

Quality

Content

57%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 concise and sensibly sectioned with useful use/don't-use guidance, but it stays at a directive level: no concrete example or template is shown, the analysis steps are not explicitly sequenced, and the lone external reference is both broken and path-inconsistent.

Suggestions

Add one concrete worked example — a short annotated walkthrough of a real snippet — or an output template so the guidance is executable rather than purely directive.

Resolve the broken, inconsistent resource reference: pick a single path for the playbook and actually include the file in the bundle, or remove the dangling reference.

Number the Instruction steps and map each to an Output Format section so the multi-step analysis flow is explicit rather than implied.

Dimension	Reasoning	Score
Conciseness	The ~40-line body is lean, well-sectioned, and does not explain concepts Claude already knows; the only minor trimmable redundancy is the opening paragraph that nearly duplicates the frontmatter description and the resource reference appearing in two places.	4 / 5
Actionability	The Instructions are high-level directives ("Assess structure, dependencies, and complexity hotspots", "Explain the high-level flow, then drill into key components") with no concrete worked example, output template, or sample annotated walkthrough to make the guidance executable.	3 / 5
Workflow Clarity	A rough sequence is implied by the Instructions plus the Output Format section (assess → high-level flow → drill in → pitfalls), but the steps are not explicitly ordered or tied to checkpoints, so the sequence is present but implicit.	3 / 5
Progressive Disclosure	The overview points to a one-level-deep reference (the implementation playbook) in a dedicated Resources section, but the referenced file does not exist in the bundle and the body gives two inconsistent paths ("resources/implementation-playbook.md" vs "./sub-skills/implementation-playbook.md"), which is a real organization gap.	3 / 5
	Total	13 / 20 Passed

Description

53%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 conveys a clear purpose and niche but is weakened by second-person voice, absent "Use when..." trigger guidance, and thin natural-language trigger terms. It reads more as a persona statement than a Claude skill description.

Suggestions

Rewrite in third person (e.g., "Explains complex code through clear narratives...") instead of "You are a code education expert..." to avoid the second-person voice penalty on specificity.

Add an explicit "Use when..." clause with concrete trigger phrases (e.g., "Use when the user asks to explain, walk through, or understand code, algorithms, or system architecture") to lift completeness above the cap of 3.

Broaden trigger-term coverage with natural synonyms users actually say — "walkthrough", "onboarding", "tutorial", "trace through code" — rather than only descriptive method terms.

Dimension	Reasoning	Score
Specificity	The description names the domain and lists concrete actions ("clear narratives, visual diagrams, and step-by-step breakdowns") which would rate a 4, but it opens with second-person voice ("You are a code education expert...") which triggers the -1 voice penalty, bringing it to 3.	3 / 5
Completeness	It gives a clear "what" (explaining code via narratives, diagrams, step-by-step breakdowns) but provides no "Use when..." clause or equivalent trigger guidance, so completeness is capped at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	It includes some relevant keywords ("explaining complex code", "visual diagrams", "step-by-step breakdowns") but misses common natural variations a user would actually say, such as "walkthrough", "onboarding", "tutorial", or "trace through code".	3 / 5
Distinctiveness Conflict Risk	The "code education / teaching" niche is mostly distinct from implementation or documentation skills, with only minor overlap risk against code-review or documentation skills; it is not a 5 because no explicit triggers reinforce the boundary.	4 / 5
	Total	13 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: Dokhacgiakhoa/Agent-Skills-4-Vibe-Coding-CLI
Path: .agent/skills/code-documentation-code-explain/SKILL.md
Commit: c4a059b

Reviewed: ~16 hours 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.