mermaid-graph-writer

name	mermaid-graph-writer
license	Apache-2.0
description	Writes precise, well-structured Mermaid diagrams for any visualization need. Use when creating flowcharts, sequence diagrams, state machines, ER models, timelines, mindmaps, Gantt charts, or any other Mermaid-supported diagram type. Activate on "mermaid", "diagram", "flowchart", "sequence diagram", "state diagram", "ER diagram", "visualize", "draw graph". NOT for rendering/exporting Mermaid to images (use mermaid-graph-renderer), ASCII art, or GUI-based design tools.
allowed-tools	Read,Write,Edit
argument-hint	[description-of-what-to-visualize]
metadata	{"category":"Content & Writing","tags":["mermaid","graph","writer","diagram","flowchart"],"pairs-with":[{"skill":"mermaid-graph-renderer","reason":"The writer creates the diagram syntax that the renderer converts to visual output"},{"skill":"diagramming-expert","reason":"ASCII/Unicode diagramming expertise informs Mermaid syntax structure and layout decisions"},{"skill":"technical-writer","reason":"Mermaid diagrams are embedded in technical documentation to explain system architecture"}]}
category	Data & Analytics
tags	["mermaid","diagramming","graph-writing","flowcharts","documentation"]

Mermaid Graph Writer

Writes precise, well-structured Mermaid diagrams by selecting the optimal diagram type, applying correct syntax, and producing diagrams that are readable by both humans and agents.

Decision Points

Primary Diagram Type Selection

Content Type → Decision Logic:
├── Sequential interactions with timing?
│   ├── If protocol/API calls → sequenceDiagram
│   └── If user journey with emotions → journey
├── States with transitions?
│   ├── If lifecycle/status changes → stateDiagram-v2
│   └── If git branching → gitGraph  
├── Branching logic or process flow?
│   ├── If <15 nodes → flowchart TD/LR
│   └── If >15 nodes → break into subgraphs or multiple diagrams
├── Data relationships?
│   ├── If tables/entities → erDiagram
│   └── If class hierarchy → classDiagram
├── Temporal progression?
│   ├── If events over time → timeline
│   └── If project tasks → gantt
├── Hierarchical concepts?
│   ├── If brainstorm/taxonomy → mindmap
│   └── If proportional hierarchy → treemap
├── System architecture?
│   ├── If cloud/infrastructure → architecture-beta
│   ├── If containers/contexts → C4Context/C4Container
│   └── If component blocks → block-beta
└── Data visualization?
    ├── If categories/proportions → pie
    ├── If 2-axis comparison → quadrantChart  
    ├── If flow quantities → sankey-beta
    └── If numerical trends → xychart-beta

Flowchart Direction Choice

Content Flow → Direction:
├── Decision tree with branching conditions?
│   └── Use TD (top-down) - questions flow down to answers
├── Sequential process steps?
│   └── Use LR (left-right) - time flows left to right
├── Dependency relationships?
│   └── Use BT (bottom-up) - dependencies point upward
└── Reverse chronology?
    └── Use RL (right-left) - latest first

Node Shape Selection for Flowcharts

Node Purpose → Shape:
├── Decision/condition? → {Diamond}
├── Start/end point? → ([Stadium])
├── Process step? → [Rectangle]
├── Data store? → [(Cylinder)]
├── External system? → [[Subroutine]]
├── Event/trigger? → ((Circle))
└── Input/output? → [/Parallelogram/]

Edge Cases - C4 vs Architecture

System Scope → Choice:
├── Single application context?
│   └── C4Context (shows external systems)
├── Internal containers of one system?
│   └── C4Container (shows APIs, DBs, web apps)
├── Component details within container?
│   └── C4Component (shows classes, modules)
└── Multiple cloud services/infrastructure?
    └── architecture-beta (shows regions, clusters)

Complexity Thresholds - Sankey vs Flowchart

Flow Visualization → Decision:
├── Quantities flowing between categories?
│   ├── If proportional amounts matter → sankey-beta
│   └── If just showing connections → flowchart LR
├── >5 parallel flows?
│   └── sankey-beta (handles parallel flows better)
└── <5 flows with decision points?
    └── flowchart (shows branching logic clearly)