mermaid_skill

Overview

This skill guides creation, editing, validation, and optional rendering of Mermaid diagrams from natural language, code analysis, or existing .mmd files. It produces syntactically correct Mermaid code, saves it to kebab-case .mmd files, validates with mermaid-cli, auto-corrects errors, and renders images only when requested. The goal is clear, maintainable diagrams you can preview or export as SVG/PNG/PDF.

How this skill works

I determine the diagram type (flowchart, sequence, class, state, ER, Gantt, etc.), extract entities and relationships from your description or source code, and generate Mermaid code using appropriate syntax and naming conventions. I save the file with a meaningful kebab-case name, run mmdc -i <filename>.mmd to validate, analyze any error output, apply automatic fixes, and re-validate until successful. Rendering to SVG/PNG/PDF is performed only when you explicitly request an image preview.

When to use it

• You want a new Mermaid diagram from a textual description or system spec.
• You need a diagram generated from source code (classes, sequences, states, flows).
• You have an existing .mmd file that needs fixing or updating.
• You want validated, ready-to-render Mermaid code with meaningful filenames.
• You need a preview image (SVG/PNG/PDF) only after validation.

Best practices

• Choose the right diagram type before generating code (flowchart, sequence, class, etc.).
• Use meaningful node IDs and concise labels; prefer kebab-case filenames like user-authentication-flow.mmd.
• Group related elements with subgraphs and use classDefs for consistent styling.
• Keep diagrams focused; split large diagrams into smaller linked files.
• Always validate with mmdc and let the skill auto-correct errors before rendering.

Example use cases

• Generate a user-authentication flowchart from a brief text description and save as user-authentication-flow.mmd.
• Analyze Python classes to produce a class diagram showing inheritance and composition.
• Convert API call traces into a sequence diagram that visualizes interactions and async calls.
• Fix a failing .mmd file by validating with mermaid-cli, applying suggested fixes, and returning corrected code.
• Render an SVG preview of a validated diagram on explicit request.