explain
Deep explanation of complex code, files, or concepts. Routes to expert agents, uses structural search, generates mermaid diagrams. Triggers on: explain, deep dive, how does X work, architecture, data flow.
68
59%
Does it follow best practices?
Impact
75%
2.14xAverage score across 3 eval scenarios
Risky
Do not use without reviewing
Optimize this skill with Tessl
npx tessl skill review --optimize ./data/skills-md/0xdarkmatter/claude-mods/explain/SKILL.mdQuality
Discovery
92%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description that clearly communicates capabilities and trigger conditions. It lists concrete actions (expert agent routing, structural search, mermaid diagram generation) and provides explicit trigger terms. The main weakness is that some trigger terms like 'explain' are broad enough to potentially conflict with other skills, and the scope ('code, files, or concepts') is quite expansive.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'routes to expert agents', 'uses structural search', 'generates mermaid diagrams'. These are distinct, concrete capabilities beyond vague language. | 3 / 3 |
Completeness | Clearly answers both 'what' (deep explanation, routing to expert agents, structural search, mermaid diagrams) and 'when' (explicit 'Triggers on:' clause with specific trigger terms). | 3 / 3 |
Trigger Term Quality | Includes natural trigger terms users would actually say: 'explain', 'deep dive', 'how does X work', 'architecture', 'data flow'. These are realistic phrases users would use when seeking deep code explanations. | 3 / 3 |
Distinctiveness Conflict Risk | While 'mermaid diagrams' and 'structural search' are distinctive, terms like 'explain' and 'how does X work' are quite broad and could overlap with general Q&A or documentation skills. The scope of 'complex code, files, or concepts' is also fairly wide. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is significantly over-engineered and verbose for what it accomplishes. It explains concepts Claude already understands (how to write mermaid diagrams, how to structure markdown explanations, what sequence diagrams are) and includes a full output template that wastes tokens. The concrete CLI tool commands with fallbacks are valuable, but they're buried in excessive scaffolding and descriptive content that should either be trimmed or split into referenced files.
Suggestions
Remove the entire Step 4 output template—Claude already knows how to structure explanations with mermaid diagrams, dependency tables, and design decision sections. Replace with a brief list of required sections.
Extract the CLI tool reference table, expert routing table, and depth/focus mode descriptions into a separate REFERENCE.md file, keeping only the core workflow in SKILL.md.
Add validation/error handling steps: what to do when ast-grep finds no matches, when the target is ambiguous, or when context gathering returns insufficient results.
Cut the three separate mermaid diagram examples (flowchart, sequence, class) down to a single note like 'Include appropriate mermaid diagram (flowchart for control flow, sequence for interactions, class for structures).'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~250+ lines. The ASCII architecture diagram, extensive mermaid diagram templates, routing tables, and explanation output templates are all things Claude already knows how to produce. The full markdown output template is particularly wasteful—Claude doesn't need to be shown how to structure markdown explanations. | 1 / 3 |
Actionability | Contains concrete bash commands and tool invocations (ast-grep, tokei, rg, fd) with fallbacks, which is useful. However, much of the content is descriptive rather than executable—the routing table, output template, and depth/focus mode descriptions are conceptual frameworks rather than copy-paste-ready instructions. The 'Task tool with subagent_type' invocation is pseudocode. | 2 / 3 |
Workflow Clarity | The 5-step architecture is clearly sequenced and the ASCII diagram provides a good overview. However, there are no validation checkpoints or error recovery steps—what happens if ast-grep finds nothing? If the expert agent produces a poor explanation? No feedback loops for verifying the quality or completeness of gathered context before proceeding. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files. The full mermaid diagram templates, complete output format template, and extensive tables are all inlined when they could be split into referenced files. The content that should be in separate reference docs (output template, CLI tool reference, expert routing rules) bloats the main skill file. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- NeverSight/skills_feed
- Commit
f772de4
- 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.