yassimba/loom/mermaid-skill

Mermaid Diagrams

Author .mmd text files and compile them to images with mmdc. Mermaid lays everything out automatically — no coordinates — and the text source lives in git and embeds in Markdown.

Route elsewhere when the request needs: pixel-precise placement, branded icons, or heavy styling → drawio; a hand-drawn aesthetic → excalidraw/tldraw; a freeform whiteboard → tldraw; strict conventional UML notation → plantuml.

Setup

mmdc renders through Puppeteer and needs a headless Chrome:

npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell   # mmdc has no bundled browser

`Could not find Chrome` is a toolchain failure, never a diagram error. mmdc --version passes without Chrome, and a perfectly valid .mmd still fails to compile. Install the browser above or set PUPPETEER_EXECUTABLE_PATH to a system Chrome; leave the .mmd alone.

Workflow

1. Author — pick the type from the shape of the content:

One diagram answers one question — past ~20 nodes, split by concern into separate .mmds instead of cramming. Syntax references, consult when unsure: FLOWCHART · SEQUENCE · CLASS-ER · ARCHITECTURE (architecture-beta — newer syntax, read before first use) · OTHER-TYPES (state, gantt, gitGraph, pie, mindmap, journey, timeline, quadrant, xychart, C4). Done when every node, participant, and label names a real thing from the content being diagrammed — no placeholders.

1. Compile — the compile is the syntax check; a parse error is a bug in the .mmd, fix and re-compile until it renders:

``bash mmdc -i diagram.mmd -o diagram.png --size 2048 ``

Themes: -t default|dark|neutral|forest (base works only inside a %%{init: {'theme':'base'}}%% directive). SVG/PDF: same command with .svg/.pdf output.

1. Self-check (vision) — a clean compile only proves the syntax; read the exported PNG and judge it as its audience will. Mermaid positions everything itself, so look for content defects, not overlaps:

Re-compile after every fix. Max 2 self-check rounds, then show the user regardless. No vision available → skip straight to the review loop.

1. Review loop — show the image, apply the minimal .mmd edit per request, re-compile. Overwrite the same .mmd/.png each round — no v1, v2, … After 5 rounds, suggest the user fine-tune at mermaid.live.

1. Report — give the user the .mmd and image paths.

Gotchas