mermaid-diagram
Generate Mermaid diagrams from user requirements. Save .mmd and .md files to figures/ with syntax verification. Supports flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, and many more diagram types.
75
68%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/skills-codex/mermaid-diagram/SKILL.mdQuality
Discovery
82%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 with excellent specificity and trigger term coverage, clearly enumerating supported diagram types and concrete actions like file saving and syntax verification. The main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know precisely when to select this skill over others. Adding trigger guidance would elevate this from good to excellent.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create a diagram, visualize a workflow, generate a Mermaid chart, or needs a visual representation of relationships or processes.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Generate Mermaid diagrams', 'Save .mmd and .md files to figures/', 'syntax verification', and enumerates specific diagram types (flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts). | 3 / 3 |
Completeness | Clearly answers 'what does this do' (generate Mermaid diagrams, save files, verify syntax, supports various diagram types), but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric guidelines. | 2 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'Mermaid', 'diagrams', 'flowcharts', 'sequence diagrams', 'class diagrams', 'ER diagrams', 'Gantt charts', '.mmd'. These cover a good range of terms users would naturally use when requesting diagram generation. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with clear niche: Mermaid diagrams specifically, with file format (.mmd), output directory (figures/), and specific diagram types. Unlikely to conflict with other skills due to the specificity of the Mermaid ecosystem. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
55%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill has excellent workflow clarity with well-defined steps, validation loops, and a thorough review checklist, and it provides highly actionable, executable guidance. However, it is severely bloated with reference material (math syntax tables, academic style guides, color palettes, diagram type catalogs) that should be split into separate files, resulting in poor conciseness and progressive disclosure. The core workflow (~80 lines) is buried in ~250 lines of reference content.
Suggestions
Extract the KaTeX math reference, academic style guide, architecture diagram best practices, and diagram type table into separate referenced files (e.g., MATH.md, ACADEMIC-STYLE.md, ARCHITECTURE-TIPS.md) and link to them from the main skill.
Remove the diagram types table entirely or reduce it to a single sentence — Claude already knows Mermaid diagram types and their use cases.
Trim the 'What to Avoid' and 'Code Quality Rules' sections which largely state things Claude already knows (e.g., 'use proper indentation', 'avoid tiny unreadable text').
Consolidate the 'Key Rules' section with the workflow steps to avoid redundant repetition of instructions already stated in the workflow (e.g., 'always verify syntax' is already Step 4).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~300+ lines. It includes extensive sections Claude already knows (Mermaid diagram types table, KaTeX syntax reference, common math patterns table, academic color palettes, general 'what to avoid' lists). The architecture diagram best practices, full CVPR/ICLR style guide, and math formula reference could easily be separate files. Much of this is reference material that inflates the token cost significantly. | 1 / 3 |
Actionability | The skill provides fully executable bash commands for directory creation, verification via mmdc, concrete file naming conventions, and specific code examples (e.g., the attention mechanism flowchart, architecture junction routing). The workflow steps are concrete and copy-paste ready. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced (Steps 0-6) with explicit validation checkpoints: Step 4 mandates syntax verification with mmdc, includes error recovery loops with MAX_ITERATIONS, and Step 5 provides a detailed review checklist with accept/fix feedback loop. This is a well-structured multi-step process with proper validation gates. | 3 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files. The KaTeX math reference, academic style guide, architecture diagram best practices, and diagram type table should all be in separate referenced files. Everything is inlined into a single massive document, making it a poor use of progressive disclosure. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Commit
dc00dfb
- 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.