mermaid-diagram

Create Mermaid diagram files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts.

Quality

76%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./SKILL.md

Quality

Content

85%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a well-structured, highly actionable skill that excels at progressive disclosure and workflow clarity. The design process is clearly sequenced with mandatory validation, and reference files are well-organized with clear loading triggers. The main weakness is moderate verbosity—the philosophical framing (Core Philosophy, Isomorphism/Education tests) and extensive audience-matching tables could be condensed without losing actionability.

Suggestions

Condense the 'Core Philosophy' and 'Assess Depth and Audience' sections—the Bad/Good comparison tables and audience node-count tables are useful but could be ~40% shorter while preserving the same guidance.

Dimension	Reasoning	Score
Conciseness	The skill is quite long (~250 lines) and includes some philosophical content (Core Philosophy, Isomorphism Test, Education Test) that borders on unnecessary for Claude. The 'Bad vs Good' tables and audience-matching tables add bulk. However, most content is genuinely instructive and specific to the task, so it's not egregiously verbose—just could be tightened.	2 / 3
Actionability	The skill provides concrete, executable guidance: specific bash commands for rendering, exact quoting rules with examples, a clear decision matrix mapping patterns to diagram types with file references, specific node naming conventions, and a detailed render-validate loop with real error recovery steps.	3 / 3
Workflow Clarity	The design process is clearly sequenced (Steps 0-7) with an explicit mandatory render-validate loop (write → render → check error/layout → fix → re-render). The feedback loop for both syntax errors (3a) and layout issues (3b/4) is well-defined with clear stopping criteria. The quality checklist provides a comprehensive validation checkpoint.	3 / 3
Progressive Disclosure	Excellent progressive disclosure with a clear reference table at the top specifying exactly when to load each reference file. Detailed syntax is deferred to `references/types/<type>.md`, theming to `references/mermaid-theme.md`, debugging to `references/syntax-pitfalls.md`, and examples to `references/examples/`. All references are one level deep and clearly signaled.	3 / 3
	Total	11 / 12 Passed

Description

67%

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 has a solid structure with an explicit 'Use when' clause, which is good for completeness. However, it lacks specificity in the concrete actions it can perform (e.g., specific diagram types like flowcharts, sequence diagrams, ER diagrams) and could include more natural trigger terms users might use. The broad visualization triggers create some overlap risk with other diagramming tools.

Suggestions

Add specific Mermaid diagram types as concrete actions, e.g., 'Create Mermaid flowcharts, sequence diagrams, class diagrams, ER diagrams, and Gantt charts'.

Expand trigger terms to include common user phrases like 'flowchart', 'sequence diagram', 'graph', '.mmd files', or 'markdown diagram'.

Dimension	Reasoning	Score
Specificity	Names the domain (Mermaid diagrams) and a general action ('create... files that make visual arguments'), but doesn't list specific concrete actions like creating flowcharts, sequence diagrams, class diagrams, Gantt charts, etc.	2 / 3
Completeness	Clearly answers both 'what' (create Mermaid diagram files that make visual arguments) and 'when' (use when the user wants to visualize workflows, architectures, or concepts) with an explicit 'Use when' clause.	3 / 3
Trigger Term Quality	Includes some natural keywords like 'Mermaid', 'visualize', 'workflows', 'architectures', 'concepts', but misses common variations users might say such as 'diagram', 'flowchart', 'sequence diagram', '.mmd', or 'graph'.	2 / 3
Distinctiveness Conflict Risk	Specifying 'Mermaid diagram files' provides some distinctiveness, but the broad triggers 'visualize workflows, architectures, or concepts' could overlap with other diagramming or visualization skills (e.g., PlantUML, draw.io, general architecture tools).	2 / 3
	Total	9 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: mgranberry/mermaid-diagram-skill
Commit: 491c608

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