home / skills / kevinslin / llm / dev.mermaid

dev.mermaid skill

safe

This skill helps generate valid Mermaid diagrams by enforcing proper label quoting and syntax, ensuring all diagrams render without parsing errors.

npx playbooks add skill kevinslin/llm --skill dev.mermaid

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: dev.mermaid
description: Generate Mermaid diagrams with proper syntax. Use when creating flowcharts, sequence diagrams, class diagrams, or any other Mermaid visualizations. Ensures correct label quoting to prevent parsing errors.
---

# Dev Mermaid

## Overview

This skill provides syntax guidelines for generating valid Mermaid diagrams. Mermaid is a diagramming language that renders text into diagrams, but it's strict about parsing—improper syntax causes rendering failures.

## Syntax Rules

When generating Mermaid:

1. **Always wrap node labels in double quotes** if they contain any of the following:

   * Parentheses `(` `)`
   * Commas `,`
   * Arrows like `->`, `=>`, `→`
   * Function-like text (e.g. `foo(a, b)`)
   * Operators or symbols (`+`, `-`, `_` in method names combined with punctuation)

2. Use this pattern:

   ```
   A["label text here"]
   ```

   not:

   ```
   A[label text here]
   ```

3. `<br/>` is allowed inside quoted labels.

4. Decision nodes `{}` may remain unquoted **only** if they contain simple words (e.g. `{dryRun?}`).

5. If unsure whether a label is safe, **quote it anyway** — quoted labels always parse correctly.

6. Never rely on Mermaid to "guess" intent; Mermaid is a grammar parser, not markdown.

## Mental Model (Important)

> **Mermaid is not Markdown.**
> It is closer to a programming language.
> If something *looks like code*, Mermaid will try to parse it as code.

Quoting labels opts out of that behavior.

Overview

This skill generates Mermaid diagrams with correct, parse-safe syntax. It focuses on producing properly quoted labels and valid node/edge patterns so diagrams render reliably. The goal is to eliminate common parsing errors caused by unquoted or ambiguous labels.

How this skill works

The skill inspects labels and diagram elements to determine whether they contain characters or patterns that require quoting, then emits Mermaid-compliant lines (for example, A["label"]). It preserves allowed HTML breaks like <br/> inside quoted labels and treats decision nodes specially when they contain simple words. When in doubt it quotes labels to guarantee successful parsing.

When to use it

Creating flowcharts, sequence diagrams, class diagrams, or state diagrams with Mermaid.
Generating labels that include punctuation, parentheses, arrows, commas, or function-like text.
Embedding method names or operators that might be interpreted as Mermaid syntax.
Converting user-provided text into diagram nodes where parsing ambiguity is possible.
Automating diagram generation from code, documentation, or templates to avoid manual fixes.

Best practices

Always quote node labels that contain parentheses, commas, arrows, or punctuation: use A["label"] format.
Use <br/> inside quoted labels for line breaks; avoid unquoted HTML or special characters.
Leave simple decision nodes unquoted only when they contain plain words (e.g., {dryRun?}).
When unsure whether a label is safe, quote it — quoted labels always parse correctly.
Treat Mermaid like a programming language, not Markdown; avoid relying on Mermaid to guess intent.

Example use cases

Generate a flowchart from a process description that includes function calls like foo(a, b).
Render a sequence diagram where participant names or messages include commas or arrows.
Create class diagrams with method signatures that contain underscores, pluses, or parentheses.
Automate documentation diagrams from code comments to ensure consistent, valid syntax.
Convert user-submitted form fields into nodes without risking parser errors.

FAQ

Do I always have to quote labels?

If a label contains punctuation, parentheses, arrows, commas, or looks like code, quote it. For simple single-word labels you can omit quotes, but quoting is safe and recommended.

Can I use HTML breaks inside labels?

Yes — <br/> is allowed inside quoted labels and is the supported way to add line breaks.