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 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) Pick the simplest type that fits — flowchart > sequence > state. Don't reach for classDiagram if a flowchart works. Sketch nodes first, edges second — list the entities (boxes), then connect them. Avoid dense edge spaghetti. Iterate small — start with 5-7 nodes. Add detail only after the user confirms the structure. 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 nodes ≤ 4 words Unicode quotes ( "smart quotes" ) breaking syntax Use ASCII " everywhere in Mermaid blocks Mermaid ; line endings forgotten when used Either use newlines OR ; consistently, not mixed Forgot fenced block tag Block must be mermaid (not just ) for HA chat to render Limitations to Surface to User No floating positioning / pixel-perfect layouts (Mermaid auto-lays out) Limited styling (colors via classDef but verbose) Some node shapes don't compose (e.g. cylinders inside subgraphs can be quirky) For organic / hand-drawn / heavily-styled diagrams, recommend a draw.io / excalidraw skill instead