Pretty Mermaid Agent Skill

Pretty Mermaid

Create or render Mermaid diagrams with the bundled Node.js CLI. Use SVG for documentation and presentations; use ASCII or Unicode for terminals and plain text.

Working directory

Treat the directory containing this file as <skill-root>. Run bundled scripts from that directory, or invoke them with absolute paths. Keep user source and rendered output in the user's requested location; do not copy the renderer into their project.

Workflow

• Determine whether the user supplied Mermaid source or needs a diagram authored from prose.
• Choose the diagram type and output format from the tables below.
• Read only the relevant reference file when syntax, theme selection, or API behavior needs more detail.
• Save new source as a .mmd file, preserving user terminology and relationships.
• Render with a named theme or explicit colors.
• Inspect the result. Fix syntax, clipping, crowded layout, or unclear labels and render again.
• Return the source and output paths, plus the selected format and theme.

Do not overwrite an existing source or output file unless the user asked for replacement.

Choose a diagram type

| Need | Diagram type | Starter |

| --- | --- | --- |

| Process, decision tree, architecture | Flowchart | flowchart LR |

| API calls, messages, interactions | Sequence | sequenceDiagram |

| Lifecycle or finite-state machine | State | stateDiagram-v2 |

| Classes, modules, relationships | Class | classDiagram |

| Database entities and cardinality | ER | erDiagram |

| Bars, lines, trends, comparisons | XY chart | xychart-beta |

Read references/DIAGRAM_TYPES.md when authoring non-trivial Mermaid syntax.

Choose an output

| Output | Best for | Notes |

| --- | --- | --- |

| SVG | READMEs, docs, slides, websites | Scalable, themed, supports transparency |

| Unicode | Modern terminals and readable text previews | Default ASCII renderer output |

| Plain ASCII | Logs and restricted terminals | Add --use-ascii |

| ANSI-colored text | Interactive terminals | Set --color-mode |

Core commands

Run these from <skill-root>.

List themes

node scripts/themes.mjs

Render SVG

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --theme tokyo-night

Render terminal text

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.txt \
  --format ascii \
  --color-mode none

Add --use-ascii when Unicode box-drawing characters are not acceptable.

Batch render a directory

node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme github-dark \
  --workers 4

Use batch rendering for three or more diagrams or when consistent options must be applied to a directory.

Theme selection

• General dark documentation: tokyo-night
• GitHub dark or light surfaces: github-dark, github-light
• Print and presentations: zinc-light
• High-contrast color: dracula
• Cool, restrained palette: nord, nord-light

Read references/THEMES.md or open docs/THEME_GALLERY.md when visual theme choice matters. A named theme can be refined with explicit color flags.

Useful options

Shared styling

| Option | Purpose |

| --- | --- |

| --theme <name> | Apply one of the 15 built-in themes |

| --bg, --fg | Set required base colors |

| --line, --accent, --muted | Refine connectors, highlights, and secondary text |

| --surface, --border | Refine node fill and stroke |

| --font <name> | Set the SVG font family |

SVG

| Option | Purpose |

| --- | --- |

| --transparent | Remove the SVG background |

| --padding <n> | Set canvas padding |

| --node-spacing <n> | Set horizontal node spacing |

| --layer-spacing <n> | Set vertical layer spacing |

| --component-spacing <n> | Separate disconnected components |

| --interactive | Enable XY chart hover tooltips |

Terminal output

| Option | Purpose |

| --- | --- |

| --use-ascii | Replace Unicode box drawing with plain ASCII |

| --padding-x, --padding-y | Tune diagram spacing |

| --box-border-padding | Tune padding inside node boxes |

| --color-mode <mode> | none, auto, ansi16, ansi256, truecolor, or html |

Run node scripts/render.mjs --help or node scripts/batch.mjs --help for the authoritative CLI list.

Authoring guidance

• Prefer short, concrete labels; preserve domain-specific terms from the user.
• Use explicit edge labels when a branch or message is ambiguous.
• Keep large diagrams readable by splitting unrelated concerns instead of shrinking text.
• Use LR for wide flows and TB for narrow documents.
• Avoid communicating meaning through color alone.
• Use a light theme for print and confirm contrast against the final background.
• For unfamiliar syntax, start from assets/example_diagrams/ and consult the diagram reference.

Validation

After rendering:

• Confirm the command exits successfully and the output file is non-empty.
• Confirm SVG output begins with <svg; confirm text output contains visible diagram content.
• Inspect visual output when layout matters, especially long labels, CJK text, disconnected components, and XY charts.
• Confirm arrows, cardinalities, states, and labels match the source request.
• Report any renderer limitation instead of silently dropping unsupported syntax.

Run both npm test and npm run validate when changing this skill, its scripts, templates, or references.

Troubleshooting

• Missing dependency: run npm install in <skill-root>; the CLI also attempts a first-run install.
• Unknown theme: run node scripts/themes.mjs and use an exact listed name.
• Parse error: consult references/DIAGRAM_TYPES.md, reduce to the failing statement, then restore the diagram incrementally.
• Crowded SVG: increase --node-spacing, --layer-spacing, or --component-spacing.
• Terminal color escape codes in redirected output: use --color-mode none.

Reference routing

| Resource | Read or use when |

| --- | --- |

| references/DIAGRAM_TYPES.md | Authoring or debugging Mermaid syntax |

| references/THEMES.md | Comparing themes or defining custom colors |

| references/api_reference.md | Extending scripts or calling beautiful-mermaid directly |

| docs/THEME_GALLERY.md | Choosing a theme visually |

| assets/example_diagrams/ | Starting from a supported diagram template |

| scripts/render.mjs | Rendering one diagram |

| scripts/batch.mjs | Rendering a directory in parallel |

| scripts/themes.mjs | Listing installed themes |