mermaid-expert

Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling.

Quality

38%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/mermaid-expert/SKILL.md

Quality

Content

17%Scale 1-5

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

This skill is largely a placeholder that lists Mermaid diagram types and generic advice without providing any concrete, executable examples or actionable syntax guidance. Claude already knows what Mermaid diagram types exist and general best practices for visualization; the skill adds almost no novel, specific knowledge. The absence of any actual Mermaid code examples is a critical gap for a skill about creating Mermaid diagrams.

Suggestions

Add concrete, copy-paste ready Mermaid code examples for at least 3-4 common diagram types (flowchart, sequence, ERD, state diagram) showing both basic and styled versions.

Remove the generic 'Use this skill when' / 'Do not use this skill when' boilerplate and the vague instruction bullets ('Clarify goals, constraints, and required inputs') that waste tokens on things Claude already knows.

Include specific syntax patterns, common pitfalls, and workarounds for Mermaid rendering issues (e.g., escaping special characters, handling long labels, subgraph nesting limitations).

Either provide the referenced `resources/implementation-playbook.md` bundle file or remove the reference and inline the essential content.

Dimension	Reasoning	Score
Conciseness	The skill contains significant padding: generic 'Use this skill when' / 'Do not use this skill when' sections that add no value, vague bullet points like 'Clarify goals, constraints, and required inputs' that Claude already knows, and the Output section lists obvious items like 'Accessibility considerations' without any concrete guidance.	2 / 5
Actionability	The content is almost entirely abstract and descriptive. There are no executable Mermaid code examples, no concrete syntax demonstrations, no copy-paste ready diagrams. The only concrete element is a list of diagram type keywords, which Claude already knows. The 'Approach' section is generic advice ('Choose the right diagram type') rather than actionable instruction.	1 / 5
Workflow Clarity	The 'Approach' section lists a rough sequence (choose type, keep readable, style, test) but steps are vague and lack any concrete commands or validation checkpoints. 'Test rendering before delivery' is mentioned but no method for testing is provided. For a skill about generating Mermaid diagrams, there's no clear workflow for how to construct, validate, or iterate on a diagram.	2 / 5
Progressive Disclosure	The skill references `resources/implementation-playbook.md` but no bundle files are provided, making this a dead reference. The content that is present is a flat list of vague instructions with no meaningful structure separating quick-start from advanced usage. The reference to the playbook is buried in a generic instruction bullet rather than clearly signaled.	2 / 5
	Total	7 / 20 Passed

Description

58%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 clearly identifies the domain (Mermaid diagrams) and lists several specific diagram types, providing reasonable specificity. However, it lacks a 'Use when...' clause, which is critical for Claude to know when to select this skill. The phrase 'Masters syntax' is vague filler rather than a concrete capability description.

Suggestions

Add a 'Use when...' clause with trigger terms like 'Use when the user asks to create diagrams, visualize workflows, draw flowcharts, or generate Mermaid syntax'.

Replace 'Masters syntax for all diagram types and styling' with concrete actions like 'Generates valid Mermaid syntax, applies custom themes and styling, supports class diagrams, Gantt charts, state diagrams, and pie charts'.

Include natural user phrases and synonyms such as 'visualize', 'draw', 'diagram', 'chart', and file extensions like '.mmd'.

Dimension	Reasoning	Score
Specificity	Lists several specific diagram types (flowcharts, sequences, ERDs, architectures) and mentions syntax and styling. However, 'Masters syntax' is somewhat vague and doesn't describe concrete actions beyond 'Create'.	4 / 5
Completeness	Has a clear 'what' (create Mermaid diagrams for various types, handle syntax and styling) but completely lacks a 'when' clause. There is no 'Use when...' or equivalent trigger guidance, which per the rubric caps this at 3.	3 / 5
Trigger Term Quality	Includes relevant terms like 'Mermaid', 'flowcharts', 'sequences', 'ERDs', 'architectures', but misses common user phrases like 'diagram', 'class diagram', 'Gantt chart', 'state diagram', '.mmd', or 'visualize'. Also missing natural trigger phrases users would say like 'draw a diagram' or 'create a chart'.	3 / 5
Distinctiveness Conflict Risk	Specifying 'Mermaid' as the diagramming technology makes it fairly distinct. However, it could overlap with general diagramming or visualization skills. The mention of specific diagram types like ERDs and architectures helps differentiate it.	4 / 5
	Total	14 / 20 Passed

Validation

90%

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 — 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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/mermaid-expert/SKILL.md
Commit: 57c135b

Reviewed: 3 days 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.