Mermaid Diagrams Skill

Generates Mermaid diagrams and renders them to PNG using the mmdc CLI.

Reference Files

• Architecture patterns (flowchart, C4, cloud, network, microservices) → references/architecture-patterns.md
• Sequence diagram patterns (API flows, auth, CI/CD, DLP flows) → references/sequence-patterns.md

Load the relevant reference file based on diagram type requested.

Rendering Tool

Use mermaid.ink (free online renderer, no browser/install needed):

mkdir -p /home/bcaddy/.openclaw/workspace/diagrams
ENCODED=$(cat <input.mmd> | base64 -w 0)
curl -s "https://mermaid.ink/img/${ENCODED}?bgColor=white&width=2048" \
  -o /home/bcaddy/.openclaw/workspace/diagrams/<name>.png

• Output directory: /home/bcaddy/.openclaw/workspace/diagrams/
• Width: 2048px default; increase for very wide diagrams (&width=3000)
• Always create output directory first: mkdir -p /home/bcaddy/.openclaw/workspace/diagrams

Workflow

1. Identify Diagram Type

• Network/system/cloud/microservices → use flowchart or C4Context
• API/auth/data flows, step-by-step processes → use sequenceDiagram
• When in doubt: sequence for "how does X work step by step", architecture for "what does X look like"

2. Load Reference File

• Architecture → references/architecture-patterns.md
• Sequence → references/sequence-patterns.md

3. Generate Mermaid Code

• Write complete, valid Mermaid syntax
• Use descriptive node labels (not just A, B, C)
• Use subgraphs to group related components in architecture diagrams
• Use alt/loop/note blocks to add clarity in sequence diagrams
• Match the style of the patterns in the reference file

4. Save .mmd File

Save to: /home/bcaddy/.openclaw/workspace/diagrams/.mmd

Use kebab-case, descriptive filenames: auth-flow.mmd, aws-architecture.mmd, api-gateway-sequence.mmd

5. Render to PNG via mermaid.ink

ENCODED=$(cat /home/bcaddy/.openclaw/workspace/diagrams/<name>.mmd | base64 -w 0)
curl -s "https://mermaid.ink/img/${ENCODED}?bgColor=white&width=2048" \
  -o /home/bcaddy/.openclaw/workspace/diagrams/<name>.png

6. Confirm Output

Report the full path to the saved PNG. Offer to adjust layout, add components, or generate a .mmd file for further editing in mermaid.live or VS Code.

Tips

• flowchart LR for left-to-right pipelines and network flows
• flowchart TD for top-down hierarchies and cloud stacks
• Wide diagrams: increase -w (width); tall diagrams: increase -H (height)
• For very complex diagrams, break into multiple diagrams
• Always include a title comment at the top of the .mmd file: %% Title: ...