/mermaid-diagram

name: mermaid-diagram
description: Use when the user asks for a flowchart, architecture diagram, sequence diagram, ER diagram, state machine, gantt chart, or any visual that fits Mermaid syntax. Hope Agent's chat renders Mermaid blocks natively, so the diagram appears inline.
version: 1.0.0
author: Hope Agent
license: MIT
metadata:
  hermes:
    tags: [office, diagram, visualization, mermaid, architecture]
    related_skills: []

Mermaid Diagram

When to Use

Trigger phrases: "draw a diagram", "flowchart for …", "sequence diagram", "architecture diagram", "ER diagram", "state machine", "gantt chart", "画一个流程图", "画个架构图".

**Mermaid is rendered natively** in Hope Agent chat (via Streamdown). Just emit a fenced ```mermaid block — the user sees the rendered SVG, no setup.

For diagrams Mermaid can't express (organic shapes, custom illustrations, hand-drawn style) consider drawing-tool skills (e.g. `excalidraw` from Hermes Agent or `drawio` from Anthropic marketplace) — those need to be installed via Quick Import.

Pick the Right Diagram Type

| Intent | Mermaid type | Use when | |--------|--------------|----------| | Step-by-step process | `flowchart` | Decisions, branching, "if X then Y" | | Time-ordered messages between actors | `sequenceDiagram` | API call traces, distributed protocols | | State transitions of a single entity | `stateDiagram-v2` | UI state machines, workflow engines | | Data model relationships | `erDiagram` | Database schema, entity relationships | | Project schedule / timeline | `gantt` | Roadmaps, sprints | | Pie / distribution | `pie` | Quick share-of-X visualization | | Tree hierarchy (org chart, decomposition) | `flowchart TD` with subgraphs | Org / breakdown trees | | Class hierarchy with methods | `classDiagram` | OO design, type relationships | | User journey (steps + sentiment) | `journey` | UX flows |

If unsure, default to `flowchart`. It's the most flexible.

Templates

Flowchart (top-down)

flowchart TD
    Start([Start]) --> Decision{Condition?}
    Decision -->|Yes| ActionA[Do A]
    Decision -->|No| ActionB[Do B]
    ActionA --> End([End])
    ActionB --> End

Sequence Diagram

sequenceDiagram
    participant U as User
    participant W as Web Server
    participant DB as Database

    U->>W: HTTP GET /api/items
    W->>DB: SELECT * FROM items
    DB-->>W: rows
    W-->>U: JSON response

    Note over U,DB: Round trip < 50ms

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch()
    Loading --> Success: 200 OK
    Loading --> Error: 4xx / 5xx
    Success --> Idle: reset()
    Error --> Idle: retry()
    Error --> [*]: give up

ER Diagram

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered as"
    USER {
        string id PK
        string email UK
        string name
    }
    ORDER {
        string id PK
        string user_id FK
        datetime created_at
    }

Gantt

gantt
    title Q3 Roadmap
    dateFormat  YYYY-MM-DD
    section Auth
    Refactor middleware     :done,    a1, 2026-04-01, 2026-04-15
    OAuth migration         :active,  a2, 2026-04-15, 30d
    section Dashboard
    Search MVP              :         d1, 2026-05-01, 14d
    Analytics rewrite       :         d2, after d1, 21d

Architecture (flowchart with subgraphs)

flowchart LR
    subgraph Frontend
        UI[React SPA]
    end
    subgraph Backend
        API[REST API]
        WS[WebSocket Hub]
    end
    subgraph Storage
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI -->|HTTPS| API
    UI -->|WSS| WS
    API --> DB
    API --> Cache
    WS --> Cache

Workflow

1. **Clarify intent** — if the user just says "diagram", ask via `ask_user_question`:

• What's the diagram showing? (process / structure / relationships / timeline)
• Who's the audience? (engineers / execs / customers)
• Level of detail? (high-level overview / fine-grained)

2. **Pick the simplest type that fits** — flowchart > sequence > state. Don't reach for `classDiagram` if a flowchart works.

3. **Sketch nodes first, edges second** — list the entities (boxes), then connect them. Avoid dense edge spaghetti.

4. **Iterate small** — start with 5-7 nodes. Add detail only after the user confirms the structure.

5. **Verify renderability** — if you reference Mermaid syntax that's iffy (e.g. classDiagram with annotations), keep it minimal. The user will see if it doesn't render.

Style Rules

• **One concept per diagram** — if you're tempted to add a second flow, split into two diagrams
• **Consistent shape vocabulary**:
• `[Square]` = process / action
• `(Round)` = entity / data
• `{Diamond}` = decision
• `([Stadium])` = start / end
• `[(Cylinder)]` = database / storage
• `((Circle))` = external system
• **Direction**: `TD` (top-down) for hierarchies, `LR` (left-right) for pipelines / data flows
• **Labels short** — node labels ≤ 4 words. Detail goes in surrounding prose.
• **Use `Note over`** in sequence diagrams to explain non-obvious behavior, not for narration

Multi-Diagram Output

When asked for "a few diagrams" or "show me the system from different angles", output 2-3 separate ```mermaid blocks with prose between them explaining what each shows.

Here's the system at three levels:

**1. High-level data flow:**
\`\`\`mermaid
flowchart LR
    ...
\`\`\`

**2. Login sequence (zoom into auth):**
\`\`\`mermaid
sequenceDiagram
    ...
\`\`\`

**3. Database relationships:**
\`\`\`mermaid
erDiagram
    ...
\`\`\`

Common Pitfalls

| Mistake | Fix | |---|---| | Single diagram with 30+ nodes | Split into 2-3 diagrams by concern | | Mixing types (flowchart with class fields) | Pick one type; for hybrid views, do multi-diagram | | All boxes look the same | Use shape vocabulary (decision = diamond, etc.) | | Long node labels | Move detail to prose; keep nod