CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

54%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

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

SKILL.md
Quality
Evals
Security

Quality

Content

42%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 has a sensible section layout and a reasonable explanation workflow, but the instructions stay at the level of high-level hints with no concrete examples or templates, and the sole external reference points to a nonexistent 'resources/implementation-playbook.md' (no bundle files exist at all). The verbatim repetition of the description and the meta 'Context' section add avoidable tokens.

Suggestions

Fix the dangling reference: 'resources/implementation-playbook.md' does not exist — either create the playbook under the conventional references/ directory and correct the path in both the Instructions and Resources sections, or drop the reference entirely.

Make the instructions concrete: specify how to assess complexity hotspots, which diagram formats to prefer (e.g., mermaid sequence/flow diagrams), and a worked mini-example of a step-by-step breakdown so guidance is executable rather than advisory.

Trim the verbatim repetition of the frontmatter description and the persona 'Context' paragraph; both restate what the skill is rather than telling Claude anything actionable.

DimensionReasoningScore

Conciseness

The body is short and mostly efficient, but the opening paragraph repeats the frontmatter description verbatim and the 'Context' section ('The user needs help understanding... Focus on clarity, visual aids, and progressive disclosure of complexity') is persona meta-commentary Claude does not need. This fits anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened'); it is above anchor 2 because the padding is limited to those two spots, and below anchor 4 because the duplication and meta-fluff are real trim candidates.

3 / 5

Actionability

The instructions are high-level hints rather than concrete guidance: 'Assess structure, dependencies, and complexity hotspots', 'Explain the high-level flow, then drill into key components', 'Use diagrams, pseudocode, or examples when useful'. There are no specific commands, templates, diagram formats, or worked examples in the body, and the file promised to hold them ('resources/implementation-playbook.md') does not exist. This matches anchor 2 ('minimal concrete guidance; high-level hints but missing the specific steps to execute'); it is not a 1 because the Output Format section does define a concrete deliverable structure.

2 / 5

Workflow Clarity

A rough sequence is present — assess structure/dependencies first, then high-level flow, then drill into components, then pitfalls — and the Output Format section mirrors it as a deliverable checklist. However the steps are loosely defined with implicit ordering and no checkpoints (e.g., nothing about verifying the explanation against the actual code or how to handle very large codebases). This fits anchor 3 ('sequence present but checkpoints missing or implicit'); it is above anchor 2 because the sequence is coherent, and below anchor 4 because the steps lack operational specificity.

3 / 5

Progressive Disclosure

The body is well-sectioned (Use when / Do not use / Context / Requirements / Instructions / Output Format / Resources), but scored against the actual bundle structure there are no bundle files at all — no references/, scripts/, or assets/ directories exist — and the single external reference 'resources/implementation-playbook.md' is a dangling path that would dead-end the reader. This fits anchor 3 ('some structure, references present but flawed organization/navigation'); it is not a 4 or 5 because the one promised detailed resource is inaccessible, and not a 2 because the sections themselves are clear and the reference is clearly signaled rather than buried.

3 / 5

Total

11

/

20

Passed

Description

45%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 states a clear purpose (explaining complex code through narratives, diagrams, and step-by-step breakdowns) but is written in second person rather than the required third person, and completely lacks a 'Use when...' trigger clause, which caps completeness. Keywords are relevant but miss natural variations users would actually say.

Suggestions

Rewrite in third person voice, e.g., 'Explains complex code, algorithms, and system behavior through clear narratives, visual diagrams, and step-by-step breakdowns' — the second-person 'You are a code education expert' opening costs a specificity point.

Add an explicit trigger clause, e.g., 'Use when the user asks to explain, walk through, or understand existing code, algorithms, or system behavior, or wants onboarding or learning materials.'

Include natural synonyms users would say — 'walk through this code', 'how does this work', 'onboarding', 'code walkthrough' — to improve trigger-term coverage and distinctiveness from documentation-writing skills.

DimensionReasoningScore

Specificity

The description names the domain ('code education', 'explaining complex code') and lists a few actions ('clear narratives, visual diagrams, and step-by-step breakdowns', 'Transform difficult concepts into understandable explanations'), which fits anchor 3 (domain plus 1-2 concrete actions, not comprehensive). However, the judging guideline mandates a 1-point reduction for second-person voice — the description opens with 'You are a code education expert' — lowering it to 2. It is not a 1 because the actions named are more concrete than purely generic language.

2 / 5

Completeness

The 'what' is reasonably clear (explain complex code via narratives, diagrams, and step-by-step breakdowns), but the 'when' is entirely absent — there is no 'Use when...' clause or equivalent trigger guidance, which the guidelines state caps completeness at 3. It fits anchor 3 ('clear what but when missing') rather than anchor 4, and is not a 2 because the 'what' is not vague.

3 / 5

Trigger Term Quality

Some natural keywords users would say are present ('explaining complex code', 'step-by-step breakdowns', 'developers'), but common trigger phrases like 'walk me through this code', 'how does this work', 'understand this algorithm', or 'onboarding' are missing, and there are no synonyms or variations. This matches anchor 3 ('some relevant keywords but missing common variations or synonyms'); it is above anchor 2 because the terms present are more specific and natural than generic filler like 'works with files'.

3 / 5

Distinctiveness Conflict Risk

The niche (code explanation/education) is somewhat specific, but 'explaining complex code... for developers at all levels' overlaps with documentation-writing, tutoring, and code-review skills, and without any 'use when' triggers it could fire for adjacent requests. This matches anchor 3 ('somewhat specific but could still overlap with similar skills'); it does not reach anchor 4 because no distinct triggers separate it from closely related skills.

3 / 5

Total

11

/

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

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

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.