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.
55
61%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
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 distinctiveness, clearly enumerating supported diagram types and concrete outputs. The main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill. Adding trigger guidance would elevate this from good to excellent.
Suggestions
Add a 'Use when...' clause such as 'Use when the user asks to create diagrams, visualize workflows, generate Mermaid syntax, or needs flowcharts, sequence diagrams, or other visual representations.'
| 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' (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 dimension at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'Mermaid', 'diagrams', 'flowcharts', 'sequence diagrams', 'class diagrams', 'ER diagrams', 'Gantt charts', '.mmd', '.md'. These cover a good range of terms users would naturally use when requesting diagram creation. | 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
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill has a well-structured workflow with strong validation and feedback loops (Steps 0-6), which is its primary strength. However, it is severely bloated — the academic style guide, KaTeX math reference, architecture diagram tips, and exhaustive diagram type table all belong in separate reference files rather than inline. The verbosity undermines token efficiency significantly, and the elaborate self-scoring rubric with ASCII aliases adds complexity without proportional value.
Suggestions
Extract the academic style guide, math/KaTeX reference, architecture diagram best practices, and diagram type table into separate reference files (e.g., ACADEMIC-STYLE.md, MATH-REFERENCE.md, ARCHITECTURE-TIPS.md) and link to them from the main skill.
Remove the detailed self-scoring rubric (Step 5) or drastically simplify it — a simple checklist of 4-5 critical items (syntax valid, arrows correct, labels correct, all components present) would suffice without the scoring breakdown guide and ASCII aliases.
Cut the diagram type table to just the type names since Claude already knows their use cases, or move it to a reference file.
Add one complete end-to-end example showing the full workflow from a concrete user request to final output files, replacing the abstract <diagram-name> placeholders with actual values.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~300+ lines. It includes extensive tables of diagram types Claude already knows, explains concepts like what flowcharts and sequence diagrams are used for, includes a full academic style guide with hex color codes, a detailed scoring rubric with ASCII aliases, and a math reference table — much of which is either common knowledge for Claude or could be in separate reference files. The self-review/scoring section alone is massively over-engineered. | 1 / 3 |
Actionability | The skill provides some concrete commands (mkdir, mmdc invocations) and code examples (Mermaid syntax for attention mechanism), but many steps use placeholder names like `<diagram-name>` without showing a complete end-to-end example. The verification bash script is executable but the overall workflow mixes concrete commands with vague instructions like 'Read the error carefully' and 'Plan the diagram structure before writing code.' | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced (Steps 0-6) with explicit validation checkpoints: Step 4 mandates syntax verification via mmdc with a retry loop up to MAX_ITERATIONS, and Step 5 includes a detailed review checklist with pass/fail criteria and a fix-and-retry feedback loop. The error recovery path is well-defined. | 3 / 3 |
Progressive Disclosure | Everything is crammed into a single monolithic file with no bundle files or external references. The academic style guide, math formula reference, architecture diagram best practices, and the full diagram type table should all be in separate reference files. The content that should be split across multiple files is all inline, making the skill unwieldy. | 1 / 3 |
Total | 7 / 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
31cc7b9
- 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.