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 for developers at all levels.

Quality

56%

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 ./plugins/AI-Agents-Safe-Coding-Skills-claude/skills/code-documentation-code-explain/SKILL.md

The canonical home for this skill is code-documentation-code-explain in rmyndharis/antigravity-skills

Quality

Content

63%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 skill body is concise and reasonably well-structured with a clear workflow, but its instructions stay at a high level of abstraction and the single referenced bundle file does not exist, weakening both actionability and progressive disclosure.

Suggestions

Add concrete guidance to the Instructions, such as a named diagram convention (e.g. Mermaid sequence/flow diagrams) and an example explanation skeleton, so Claude has executable patterns to follow.

Either create resources/implementation-playbook.md with the promised detailed examples and templates, or remove the two references to it.

Make the reference a real markdown link (e.g. [implementation-playbook.md](resources/implementation-playbook.md)) so navigation and file existence are verifiable.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-sectioned with no over-explanation of concepts Claude already knows; only the Context paragraph ('Focus on clarity, visual aids, and progressive disclosure of complexity to facilitate learning and onboarding') is slightly padded.	4 / 5
Actionability	Instructions are high-level hints ('Assess structure, dependencies, and complexity hotspots', 'Explain the high-level flow, then drill into key components') with no concrete diagram format, example structure, or pseudocode template, though the Output Format section adds some shape.	3 / 5
Workflow Clarity	A clear logical sequence runs from assessment through high-level flow to detailed walkthrough, mirrored by the Output Format; no validation checkpoints are needed for this non-destructive explanation task.	4 / 5
Progressive Disclosure	Section structure is good and the reference is one-level-deep and clearly signaled, but 'resources/implementation-playbook.md' is referenced in both Instructions and Resources while no resources/ directory exists, producing a broken navigation link.	3 / 5
	Total	14 / 20 Passed

Description

50%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 a few concrete capabilities but uses second-person voice, omits an explicit 'Use when...' trigger clause, and risks overlapping with related code-analysis skills. It sits at the midpoint across all dimensions.

Suggestions

Rewrite in third person ('Explains complex code through clear narratives, visual diagrams, and step-by-step breakdowns') to avoid the second-person specificity penalty.

Add an explicit trigger clause, e.g. 'Use when the user asks to explain, walk through, or break down existing code, algorithms, or system behavior.'

Sharpen distinctiveness by contrasting with implementation/review tasks, e.g. 'Use for understanding existing code, not for writing or refactoring it.'

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns') which anchors at 4, but the second-person voice ('You are a code education expert', 'Transform difficult concepts') triggers the -1 specificity penalty, landing at 3.	3 / 5
Completeness	It clearly states the 'what' (explaining complex code via narratives, diagrams, breakdowns) but provides no 'Use when...' trigger clause, so per the guidelines completeness is capped at 3.	3 / 5
Trigger Term Quality	Phrases like 'explaining complex code' and 'step-by-step breakdowns' are reasonably natural, but it misses common user variations such as 'walk me through this code', 'explain this algorithm', or 'walkthrough'.	3 / 5
Distinctiveness Conflict Risk	The code-education niche is somewhat specific, but 'explaining complex code' and 'teaching patterns' overlap with code-review, debugging-reasoning, and onboarding skills.	3 / 5
	Total	12 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills-claude/skills/code-documentation-code-explain/SKILL.md
Commit: 57c135b

Reviewed: 2 days 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.