creating-mermaid-diagrams

A skill for generating Mermaid diagrams as .mmd text files and exporting them to PNG, SVG, or PDF, using either the local mmdc CLI or the no-install Kroki API. Its core advantage is text-based syntax with fully automatic layout, so no x/y coordinates are needed. It is intended to be used whenever a user mentions a diagram, flowchart, sequence, class, ER, or state diagram, architecture, or visualization (including Chinese terms), and to be applied proactively when explaining any system with three or more components, API flows, authentication sequences, class hierarchies, database schemas, or state machines. More than eleven diagram types are supported, including flowchart, sequence, class, ER, state, Gantt, pie, git graph, C4 context, and mind map.

The workflow runs from an optional update check through choosing a diagram type, writing the .mmd file, validating, exporting, and reporting output paths. The update check is conservative: it notifies but does not pull, throttles to once per 24 hours via a .last_update file, never mutates the skill directory without explicit consent, and silently swallows failures in non-git or read-only installs. Validation is mandatory before export — a diagram is never exported without first validating it, either by rendering through mmdc or by posting to Kroki — and the doc lists common validation errors such as missing quotes around labels with special characters, wrong arrow syntax, and undeclared sequence-diagram participants.

Two export paths are documented. The local path installs @mermaid-js/mermaid-cli and runs mmdc with options for width, background color, and themes (default, dark, neutral, forest, base). The Kroki path needs only curl and posts the .mmd file to endpoints like https://kroki.io/mermaid/svg or /png, which is recommended when mmdc installation fails, for quick one-off diagrams, or in CI/CD pipelines without Node.js. The skill includes worked examples for a JWT authentication sequence, an e-commerce microservices architecture flowchart, and an order-lifecycle state machine, plus a common-mistakes table covering issues like mmdc not found, wrong sequence arrows, special characters in labels, blank or small output (fix with a wider width flag), participant ordering, and subgraph names containing spaces.