# Mermaid Skill

> Generate Mermaid diagrams as code (.mmd) and export to PNG/SVG/PDF with mmdc. Use when the user wants a diagram — flowchart, sequence, class, ER, state, gantt, git graph, architecture, timeline, mindmap — proactively when explaining a system with 3+ components, a runtime flow, a schema, or a lifecycle, and when another skill (e.g. blueprint) needs a diagram authored or exported to an image.

- **Type:** Skill
- **Install:** `agentstack add skill-yassimba-loom-mermaid-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Yassimba](https://agentstack.voostack.com/s/yassimba)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Yassimba](https://github.com/Yassimba)
- **Source:** https://github.com/Yassimba/loom/tree/main/skills/mermaid-skill

## Install

```sh
agentstack add skill-yassimba-loom-mermaid-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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:

   | The content is…                                     | Type                                     |
   | ---------------------------------------------------- | ---------------------------------------- |
   | steps, branches, dependencies                         | `flowchart`                              |
   | who calls whom, in what order                         | `sequenceDiagram`                        |
   | tables and relations / types and inheritance          | `erDiagram` / `classDiagram`             |
   | statuses one thing moves through                      | `stateDiagram-v2`                        |
   | deployed services and their wiring                    | `architecture-beta`                      |
   | schedule / branch history / proportions / idea tree   | `gantt` / `gitGraph` / `pie` / `mindmap` |
   | events over time / effort-impact grid / plotted data  | `timeline` / `quadrantChart` / `xychart-beta` |

   One diagram answers one question — past ~20 nodes, split by concern into separate `.mmd`s instead of cramming.
   Syntax references, consult when unsure:
   [FLOWCHART](reference/FLOWCHART.md) · [SEQUENCE](reference/SEQUENCE.md) · [CLASS-ER](reference/CLASS-ER.md) · [ARCHITECTURE](reference/ARCHITECTURE.md) (`architecture-beta` — newer syntax, read before first use) · [OTHER-TYPES](reference/OTHER-TYPES.md) (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.

2. **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 -w 2048
   ```

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

3. **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:

   | Check              | What to look for                      | Fix                                                                         |
   | ------------------ | ------------------------------------- | --------------------------------------------------------------------------- |
   | Label truncation   | Node / edge text clipped              | Shorten the label, or wrap with ``                                     |
   | Cramped density    | Nodes crammed together; tangled lines | Flip direction (`TD`↔`LR`), split into `subgraph`s, or reduce nodes         |
   | Wrong aspect       | Far too wide or too tall to read      | Change `flowchart TD`↔`LR` (or set `direction` in class/state)              |
   | Edge spaghetti     | Many crossings, hard to follow        | Reorder declarations so connected nodes sit adjacent; group with `subgraph` |
   | Wrong diagram type | Type doesn't suit the content         | Re-pick from the step-1 table                                               |
   | Low contrast       | Text blends into the node fill        | `classDef` ([FLOWCHART § Styling](reference/FLOWCHART.md)) or `-t` theme    |

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

4. **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](https://mermaid.live).

5. **Report** — give the user the `.mmd` and image paths.

## Gotchas

| Symptom                                              | Fix                                                                     |
| ---------------------------------------------------- | ----------------------------------------------------------------------- |
| Parse error on a label with special chars            | Quote it: `A["Label: value"]`                                           |
| Parse error on a subgraph name with spaces           | Quote it: `subgraph "My Layer"`                                         |
| `Maximum text size in diagram exceeded`              | Split the diagram; last resort `-c config.json` `{"maxTextSize": 200000}` |
| Chrome crashes in CI / as root                       | `-p puppeteer.json` with `{"args": ["--no-sandbox"]}`                   |
| Architecture icons missing / `logos:` name not found | Register the pack at compile time — [ARCHITECTURE § Icons](reference/ARCHITECTURE.md) |
| Blank or tiny PNG                                    | Add `-w 2048`                                                           |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Yassimba](https://github.com/Yassimba)
- **Source:** [Yassimba/loom](https://github.com/Yassimba/loom)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yassimba-loom-mermaid-skill
- Seller: https://agentstack.voostack.com/s/yassimba
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.