mermaid-diagrams

Comprehensive guide for creating software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams (domain modeling, object-oriented design), sequence diagrams (application flows, API interactions, code execution), flowcharts (processes, algorithms, user journeys), entity relationship diagrams (database schemas), C4 architecture diagrams (system context, containers, components), state diagrams, git graphs, pie charts, gantt charts, or any other diagram type. Triggers include requests to "diagram", "visualize", "model", "map out", "show the flow", or when explaining system architecture, database design, code structure, or user/application flows.

Quality

89%

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

Quality

Content

86%Weight 40%Scale 1-5

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

Well-structured, actionable content with executable examples across diagram types and a clean one-level-deep reference structure. It could be tightened by trimming truistic best-practice and 'when to create' padding and by adding an explicit syntax-validation step before export.

Suggestions

Trim or remove the 'Best Practices' truisms ('Use Meaningful Names', 'Keep Focused') and the 'When to Create Diagrams' section, which restate what Claude already knows.

Add an explicit validation checkpoint in the export workflow (e.g., 'Validate syntax in Mermaid Live Editor before running mmdc') to form a render-then-fix feedback loop.

The 'Common Pitfalls' items largely restate info from 'Key principles' and could be consolidated to reduce redundancy.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with quick-start examples and a selection guide, but contains some truisms in Best Practices ('Use Meaningful Names', 'Keep Focused') and a padded 'When to Create Diagrams' section that assumes little; minor over-explanation rather than verbosity.	4 / 5
Actionability	Provides fully executable, copy-paste-ready Mermaid examples for every major diagram type plus concrete export commands (mmdc CLI, docker run), covering the common cases with specific syntax.	5 / 5
Workflow Clarity	A clear selection-then-author-then-render sequence is implied via the Diagram Type Selection Guide and Exporting section, but there are no explicit validation checkpoints (e.g., 'render in Mermaid Live to validate syntax before export'); the destructive/batch cap does not apply since diagramming is non-destructive.	4 / 5
Progressive Disclosure	SKILL.md is a clear overview that points to seven well-signaled, one-level-deep reference files (class-diagrams.md, sequence-diagrams.md, etc.), all of which exist in references/, with brief descriptors enabling easy navigation.	5 / 5
	Total	18 / 20 Passed

Description

92%Weight 40%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.

A strong, comprehensive description that clearly states what the skill does and when to use it, with concrete diagram-type breakdowns and natural trigger phrases. The only minor gap is a few missing everyday synonyms like 'draw'.

Suggestions

Consider adding 'draw' or 'chart' to the trigger list, as users often say 'draw a diagram' or 'chart this flow'.

The description is long; the parenthetical per-type use-case lists could be trimmed slightly without losing the strong trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions (create, visualize, document) and enumerates specific diagram types with their use cases (class diagrams for domain modeling, sequence diagrams for API flows, ERD for database schemas, C4 for architecture), giving comprehensive coverage of capabilities.	5 / 5
Completeness	Explicitly answers both 'what' (comprehensive guide for creating software diagrams using Mermaid) and 'when' (an explicit 'Triggers include...' clause listing concrete phrases and triggering contexts).	5 / 5
Trigger Term Quality	Includes natural trigger phrases users would say ('diagram', 'visualize', 'model', 'map out', 'show the flow') plus context cues ('explaining system architecture', 'database design'), but misses a few common synonyms like 'draw' or 'chart'.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (Mermaid text-based diagramming) with distinct, specific triggers tied to diagram types and contexts, creating minimal overlap risk with other skills.	5 / 5
	Total	19 / 20 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: shep-ai/shep
Path: .claude/skills/mermaid-diagrams/SKILL.md
Commit: e86d11c

Reviewed: 1 day 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.