Mermaid Diagram

Purpose

This skill translates verbal or written descriptions of processes, architectures, data models, timelines, and relationships into correct Mermaid diagram syntax. The output is a fenced code block using the mermaid language identifier, which renders natively in Obsidian, GitHub, GitLab, Notion, and any modern Markdown environment.

Mermaid is a text-based diagramming language. It allows diagrams to be version-controlled, diffed, and embedded directly in Markdown files without image uploads. This skill handles the translation from human intent to syntactically correct Mermaid DSL.

When to Use

Invoke this skill when:

• The user asks to "draw", "create", "generate", or "diagram" something
• The user provides a process flow, system architecture, or data model in prose and wants a visual representation
• The user uploads or pastes an existing diagram image and wants its Mermaid equivalent
• The user says "add a diagram to this note" without specifying a tool
• The user explicitly mentions Mermaid, flowchart, sequence diagram, or any diagram type listed below
• The user asks to revise or extend an existing Mermaid diagram
• The user wants to visualize relationships between entities, steps in a process, or states in a system

Do NOT use this skill when:

• The user wants a hand-drawn or image-based diagram — Mermaid is text only
• The user needs interactive diagrams with click handlers — use a JavaScript library instead
• The user is working in Excalidraw — use excalidraw-diagram instead
• The user wants a whiteboard-style canvas layout — use obsidian-canvas instead

Diagram Types Reference

Workflow

Step 1: Identify the Diagram Type

Read the user's request and select the most appropriate diagram type:

• Processes with steps and decisions → flowchart TD
• Two or more actors exchanging messages → sequenceDiagram
• Classes, attributes, and methods → classDiagram
• Something that transitions between states → stateDiagram-v2
• Database tables and their relationships → erDiagram
• A hierarchy of topics or concepts → mindmap
• Tasks and dates on a timeline → gantt
• Proportions of a whole → pie

If the type is ambiguous, ask one clarifying question before generating: "What kind of diagram best fits your need — a flowchart, sequence diagram, or something else?"

Step 2: Extract the Diagram Content

From the user's description, identify:

• Nodes / entities: the main components (steps, actors, classes, states)
• Edges / relationships: how nodes connect (arrows, labels, cardinality)
• Subgroups: clusters, swimlanes, namespaces, or parent-child hierarchies
• Labels: text on edges or inside nodes
• Conditions: decision branches in flowcharts (Yes / No labels)

Step 3: Write Mermaid Syntax

Apply the correct syntax for the chosen diagram type. Output the diagram inside a fenced code block:

```mermaid
<diagram code here>
```

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -- Yes --> C[Process A]
    B -- No --> D[Process B]
    C --> E[End]
    D --> E

Node shapes:

• [Text] — Rectangle (process, step)
• {Text} — Diamond (decision)
• (Text) — Rounded rectangle (start/end)
• ((Text)) — Circle (connector)
• [/Text/] — Parallelogram (input/output)
• [(Text)] — Cylinder (database)

Direction modifiers: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left).

Subgraphs for grouping:

flowchart TD
    subgraph Backend
        B1[API] --> B2[DB]
    end
    subgraph Frontend
        F1[UI] --> F2[State]
    end
    F2 -->|HTTP| B1

Sequence Diagram

sequenceDiagram
    actor User
    participant App
    participant DB

    User->>App: Submit form
    App->>DB: INSERT record
    DB-->>App: OK
    App-->>User: Success message

Arrow types:

• ->> — Solid arrow with head (synchronous call)
• -->> — Dashed arrow with head (return / async)
• -> — Solid line, open arrow
• --> — Dashed line, open arrow

Activate/deactivate to show processing time:

sequenceDiagram
    User->>+Server: Request
    Server-->>-User: Response

Notes in sequence diagrams:

Note right of User: User is logged in
Note over App,DB: Shared transaction

Class Diagram

classDiagram
    class User {
        +String name
        +String email
        -String password
        +login() bool
        +logout() void
    }

    class Order {
        +int id
        +Date createdAt
        +List~Item~ items
        +total() float
    }

    User "1" --> "0..*" Order : places

Visibility modifiers: + public, - private, # protected, ~ package/internal.

Relationship types:

• --> — Association
• --|> — Inheritance
• ..|> — Implementation
• --* — Composition
• --o — Aggregation
• ..> — Dependency

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Success : complete
    Processing --> Failed : error
    Success --> [*]
    Failed --> Idle : retry

    state Processing {
        [*] --> Validating
        Validating --> Executing
        Executing --> [*]
    }

Use [*] for entry and exit points. Nested states model sub-processes.

Entity Relationship Diagram

erDiagram
    USER {
        int id PK
        string name
        string email UK
    }
    ORDER {
        int id PK
        int user_id FK
        date created_at
        float total
    }
    ORDER_ITEM {
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Cardinality notation:

• || — exactly one
• o| — zero or one
• }| — one or more
• }o — zero or more

Mindmap

mindmap
  root((Project))
    Planning
      Requirements
      Timeline
      Budget
    Execution
      Development
      Testing
      Deployment
    Review
      Metrics
      Retrospective

Nodes use indentation to define hierarchy. Root node uses (( )) for a circle. Child nodes can use [ ], ( ), or plain text.

Gantt Chart

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Planning
        Requirements  :done, req, 2024-01-01, 2024-01-07
        Design        :active, design, 2024-01-08, 7d
    section Development
        Backend       :backend, after design, 14d
        Frontend      :frontend, after design, 14d
    section Launch
        Testing       :crit, test, after backend, 7d
        Deploy        :deploy, after test, 1d

Task modifier keywords: done, active, crit (critical path), milestone.

Step 4: Validate the Syntax

Before outputting, mentally trace through the diagram and check:

1. All referenced IDs exist — every node ID used in an edge must be defined
2. Subgraph closures — every subgraph has a matching end
3. Arrow syntax — correct separator for the diagram type (--> vs ->> vs --|>)
4. Special characters — node labels with parentheses, brackets, or quotes must use ["label with (parens)"] to avoid parse errors
5. No unsupported syntax — mindmaps don't use arrows; ER diagrams use ||--o{ not -->

If you detect a likely syntax issue, note it explicitly: ⚠️ Note: The backslash in the label may need escaping — if the diagram fails to render, replace it with a hyphen.

Step 5: Provide Rendering Instructions

After the code block, briefly note how to render:

• Obsidian: The mermaid fence renders natively — no plugin required
• GitHub / GitLab: Renders in .md files and wikis
• VS Code: Install the "Mermaid Preview" extension
• Browser: Use mermaid.live to paste and preview

If the skill detects the note is destined for Obsidian (user mentioned vault, note, or uses wikilinks), skip saying "Obsidian requires a plugin" — Mermaid is native to Obsidian.

Output Formats

Minimal Output

For a simple diagram request, output only the fenced code block:

```mermaid
flowchart LR
    A --> B --> C
```

Full Output

For complex diagrams where context helps, include:

1. A one-line description of what the diagram shows
2. The fenced Mermaid code block
3. Any notes about rendering or extension

Embedded in a Note

When embedding in an Obsidian note, place the diagram after the relevant heading:

## Architecture Overview

```mermaid
flowchart TD
    ...

The system is composed of three layers...

## Critical Rules

**NEVER:**
- Output diagram syntax without the ```` ```mermaid ```` fence — the diagram will not render
- Mix diagram types in a single code block — use separate blocks for each diagram
- Use HTML tags inside Mermaid nodes — Mermaid has limited HTML support; use plain text
- Invent node IDs that don't match the connections — validate all references exist
- Add a `direction` keyword inside `classDiagram` — it is not supported in all Mermaid versions
- Use commas inside node labels without quoting: `A[Name, Title]` will break — use `A["Name, Title"]`

**ALWAYS:**
- Output the complete diagram, not a partial skeleton
- Pick the diagram type that best conveys the user's mental model, not the easiest to generate
- Include subgraph labels if the diagram has more than 8 nodes — group for readability
- Limit nodes to 20 or fewer in a single diagram; suggest splitting if the user's request is larger
- Test sequence diagram message labels — they appear above the arrow and must be concise
- Use `stateDiagram-v2` instead of the older `stateDiagram` — the v2 syntax is more expressive

## Example Usage

**Example 1: Process flowchart from description**

User: "Draw a flowchart for user login: user submits form, system checks credentials, if valid redirect to dashboard, if not show error"

Output:
````markdown
```mermaid
flowchart TD
    A([User submits form]) --> B{Credentials valid?}
    B -- Yes --> C[Redirect to dashboard]
    B -- No --> D[Show error message]
    D --> A

---

**Example 2: Sequence diagram for API interaction**

User: "Show the sequence when a mobile app calls our REST API to get user data"

Output:
````markdown
```mermaid
sequenceDiagram
    actor User
    participant App as Mobile App
    participant API as REST API
    participant DB as Database

    User->>App: Tap profile button
    App->>+API: GET /users/{id}
    API->>+DB: SELECT * FROM users
    DB-->>-API: User record
    API-->>-App: 200 OK { user }
    App-->>User: Display profile
```

Example 3: Class diagram for a data model

User: "Create a class diagram for a blog post system with users, posts, and comments"

Output:

```mermaid
classDiagram
    class User {
        +int id
        +String name
        +String email
        +createPost() Post
        +leaveComment() Comment
    }
    class Post {
        +int id
        +String title
        +String content
        +Date publishedAt
        +publish() void
    }
    class Comment {
        +int id
        +String body
        +Date createdAt
    }

    User "1" --> "0..*" Post : authors
    User "1" --> "0..*" Comment : writes
    Post "1" --> "0..*" Comment : has
```

Example 4: State machine for order status

User: "What are the states an order goes through from creation to delivery?"

Output:

```mermaid
stateDiagram-v2
    [*] --> Pending : Order created
    Pending --> Confirmed : Payment received
    Pending --> Cancelled : Customer cancels
    Confirmed --> Shipped : Warehouse dispatched
    Shipped --> Delivered : Carrier confirmed
    Delivered --> [*]
    Cancelled --> [*]
    Shipped --> Returned : Customer requests return
    Returned --> Refunded : Refund processed
    Refunded --> [*]
```

Example 5: Mindmap for a brainstorming session

User: "Create a mindmap for our product roadmap themes"

Output:

```mermaid
mindmap
  root((Product Roadmap))
    Growth
      Referral program
      SEO improvements
      Paid acquisition
    Retention
      Onboarding flow
      In-app notifications
      Loyalty rewards
    Platform
      Mobile app
      API v2
      Webhooks
    Compliance
      GDPR controls
      Audit logs
      Data export
```