// Must read guide on creating/editing mermaid charts with validation tools and syntax reference for all diagram types
| name | mermaid |
| description | Must read guide on creating/editing mermaid charts with validation tools and syntax reference for all diagram types |
Use this skill to quickly validate Mermaid diagrams by parsing + rendering them with the official Mermaid CLI. Includes a syntax reference for every Mermaid diagram type.
When this skill is invoked, the user may provide a file path and name as an argument:
@skills/mermaid/skill.md <filename.mmd>
Examples: vue-architecture.mmd, docs/auth-flow.mmd, db-schema.mmd
user-auth-flow.mmd, payment-sequence.mmd, order-er-diagram.mmd). Place it in the project root.diagram.mmd. Every diagram gets its own descriptively named file.npx).PUPPETEER_EXECUTABLE_PATH.The validate script lives inside the skill directory. Use the path relative to the skill, not the working directory:
.agents/skills/mermaid/tools/validate.sh <filename.mmd> [output.svg]
beautiful-mermaid (best-effort; not all diagram types are supported).output.svg is omitted, the SVG is rendered to a temp file and discarded..mmd extension..agents/skills/mermaid/tools/validate.sh <filename.mmd>.Pick the right diagram for the job. Each section shows what it's for and the essential syntax.
Use for: Process flows, decision trees, workflows, algorithms.
flowchart TD
A[Start] --> B{Decision?}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
Directions: TB/TD (top-down), BT, LR, RL
Node shapes: A[rect] A(rounded) A([stadium]) A[[subroutine]] A[(cylinder)] A((circle)) A{diamond} A{{hexagon}} A[/parallelogram/] A[/trapezoid\] A(((double circle)))
Links: --> arrow, --- open, -.-> dotted, ==> thick, ~~~ invisible, <--> bidirectional. Add text: -->|text| or -- text -->
Subgraphs: subgraph id[title] ... end
Multi-line labels: \n does NOT work. Use markdown strings with backticks and real newlines:
A["`Line 1
Line 2
Line 3`"]
Markdown strings also support bold and italic formatting.
Styling: style A fill:#f9f,stroke:#333 or classDef cls fill:#f9f; A:::cls
Use for: API calls, service interactions, request/response flows, protocol sequences.
sequenceDiagram
participant A as Alice
participant B as Bob
A->>B: Hello
B-->>A: Hi back
A->>B: How are you?
B-->>A: Great!
Participants: participant, actor. Stereotypes (JSON config): boundary, control, entity, database, collections, queue
Arrows: ->> solid+arrowhead, -->> dotted+arrowhead, -x cross end, -) async open arrow, <<->> bidirectional
Activations: activate A / deactivate A or shorthand A->>+B: msg / B-->>-A: reply
Notes: Note right of A: text or Note over A,B: text
Control flow:
loop text ... endalt text ... else ... endopt text ... endpar [Action 1] ... and [Action 2] ... endcritical [text] ... option [text] ... endbreak [text] ... endGrouping: box color Title ... end
Background highlight: rect rgb(0,255,0) ... end
Use for: OOP class structures, inheritance hierarchies, domain models.
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal : +int age
Animal : +String gender
Animal : +isMammal() bool
Duck : +swim()
Fish : +canEat() bool
Members: Bracket syntax Class { +method() returnType; -field type }. Visibility: + public, - private, # protected, ~ internal. Classifiers: * abstract, $ static.
Relationships: <|-- inheritance, *-- composition, o-- aggregation, --> association, ..> dependency, ..|> realization
Cardinality: ClassA "1" --> "*" ClassB
Annotations: <<Interface>>, <<Abstract>>, <<Enumeration>>, <<Service>>
Generics: List~int~
Namespaces: namespace Name { class A { } }
Notes: note "text" or note for ClassName "text"
Use for: Finite state machines, lifecycle states, object state transitions.
stateDiagram-v2
[*] --> Idle
Idle --> Processing : submit
Processing --> Done : complete
Processing --> Error : fail
Error --> Idle : retry
Done --> [*]
States: stateName, stateName : Description, state "Description" as s1
Start/End: [*] --> First, Last --> [*]
Composite: state CompositeState { InnerA --> InnerB }
Choice: state decision <<choice>>
Fork/Join: state fork <<fork>>, state join <<join>>
Notes: note right of State : text ... end note
Concurrency: state Parallel { A --> B -- C --> D } (use -- separator)
Direction: direction LR (or RL, TB, BT)
Use for: Database schemas, data models, table relationships.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
PRODUCT ||--o{ LINE-ITEM : "is in"
Cardinality: || exactly one, o| zero or one, }| one or more, o{ zero or more
Line style: -- identifying (solid), .. non-identifying (dashed)
Attributes:
ENTITY {
string name PK
int age
string email UK "user email"
}
Key types: PK, FK, UK
Use for: Project schedules, task timelines, sprint planning.
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Phase 1
Task A :a1, 2024-01-01, 30d
Task B :after a1, 20d
section Phase 2
Task C :2024-02-15, 12d
Milestone :milestone, m1, 2024-03-01, 0d
Task format: Task name :tags, id, start, end/duration. Tags: done, active, crit, milestone
Dependencies: after taskId, until taskId
Date config: dateFormat YYYY-MM-DD, axisFormat %Y-%m-%d
Excludes: excludes weekends or specific dates
Use for: Proportions, distributions, market share.
pie showData title Browser Market Share
"Chrome" : 65
"Safari" : 19
"Firefox" : 4
"Other" : 12
Syntax: pie [showData] [title text] then "label" : value per line. Values must be positive numbers.
Use for: Branch strategies, release flows, git workflows.
gitGraph
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit tag:"v1.0"
Commands: commit, branch name, checkout name, merge name, cherry-pick id:"commitId"
Commit options: id: "abc", tag: "v1.0", type: NORMAL|REVERSE|HIGHLIGHT
Use for: Brainstorming, topic hierarchies, concept maps.
mindmap
root((Central Idea))
Topic A
Subtopic 1
Subtopic 2
Topic B
Subtopic 3
Hierarchy: Indentation defines parent-child relationships.
Shapes: [square], (rounded), ((circle)), )cloud(, {{hexagon}}, ))bang(( or plain text.
Icons: ::icon(fa fa-book) after node text.
Classes: :::className after node text.
Use for: Historical events, release histories, roadmaps.
timeline
title Project Milestones
section 2024 Q1
January : Kickoff : Team formed
March : MVP released
section 2024 Q2
June : Public launch
Syntax: time period : event1 : event2 or stack events on separate lines with : event.
Sections: section Title groups subsequent entries.
Use for: UX flows, customer experience mapping, satisfaction scoring.
journey
title User Purchase Flow
section Browse
Visit site: 5: User
Search product: 3: User
section Checkout
Add to cart: 5: User
Enter payment: 2: User, System
Confirm order: 4: User, System
Syntax: Task name: score: actor1, actor2. Score is 1-5 (1=bad, 5=great).
Sections: Group tasks into phases.
Use for: Priority matrices, competitive analysis, effort-vs-impact plots.
quadrantChart
title Feature Priority
x-axis Low Effort --> High Effort
y-axis Low Impact --> High Impact
quadrant-1 Do First
quadrant-2 Plan
quadrant-3 Eliminate
quadrant-4 Delegate
Feature A: [0.8, 0.9]
Feature B: [0.2, 0.7]
Feature C: [0.6, 0.3]
Points: Label: [x, y] where x,y are 0-1. Optional: radius: 12, color: #ff3300
Use for: Flow quantities, energy/resource distribution, budget allocation.
sankey
Source A,Target X,100
Source A,Target Y,50
Source B,Target Y,80
Source B,Target Z,30
Syntax: CSV format source,target,value. Wrap commas in quotes: "A, Inc",B,100
Config: linkColor: source|target|gradient|#hex, nodeAlignment: justify|center|left|right
Use for: Data trends, comparisons, statistics.
xychart
title "Monthly Sales"
x-axis "Month" [Jan, Feb, Mar, Apr, May]
y-axis "Revenue" 0 --> 500
bar [120, 200, 150, 300, 450]
line [100, 180, 160, 280, 420]
Orientation: xychart horizontal for horizontal layout.
X-axis: categorical ["a", "b"] or numeric min --> max. Y-axis: numeric only.
Data: bar [values] and/or line [values].
Use for: System architecture layouts, infrastructure diagrams, component arrangements.
block-beta
columns 3
A["Frontend"] B["API"] C["Database"]
D["Cache"]:2 E["Queue"]
A --> B --> C
B --> D
Columns: columns N sets grid width. Blocks span columns with :N.
Shapes: Same as flowchart: [rect], (rounded), ((circle)), {diamond}, [(cylinder)], etc.
Links: -->, --- with optional text.
Nesting: Blocks can contain other blocks for composite layouts.
Space: Use space or space:N to insert empty cells.
Use for: Network protocol headers, binary data formats, memory layouts.
packet-beta
0-15: "Source Port"
16-31: "Destination Port"
32-63: "Sequence Number"
64-95: "Acknowledgment Number"
Syntax: start-end: "Field name" for ranges, or +N: "Field name" for N-bit auto-positioned fields.
Use for: Cloud infrastructure, CI/CD pipelines, service topology.
architecture-beta
group api(cloud)[API Layer]
service db(database)[PostgreSQL] in api
service server(server)[App Server] in api
service client(internet)[Client]
client:R --> L:server
server:R --> L:db
Groups: group id(icon)[Title] — containers for services. Nest with in parentId.
Services: service id(icon)[Title] — individual nodes. Nest with in groupId.
Edges: serviceA:direction --> direction:serviceB. Directions: T, B, L, R.
Junctions: junction id — four-way connection points.
Icons: Built-in: cloud, database, disk, internet, server. Custom via iconify: "logos:aws"
Use for: Task boards, workflow stages, agile boards.
kanban
todo[To Do]
task1[Design mockups]
task2[Write specs]
inprog[In Progress]
task3[Build API]
done[Done]
task4[Setup repo]
Columns: id[Title] at root level.
Tasks: id[Description] indented under a column.
Metadata: @{ assigned: "Alice", ticket: "PROJ-123", priority: "High" } after task.
Config: ticketBaseUrl in YAML frontmatter creates clickable ticket links.
Generate interactive HTML walkthroughs with clickable Mermaid diagrams (flowcharts and ER diagrams) that explain codebase features, flows, architecture, and database schemas. Use when asked to "walkthrough", "explain this flow", "how does X work", "trace the code path", "annotated diagram", "code walkthrough", "explain the architecture of", "walk me through", "database schema", "explain the tables", "data model".
Create a note from any resource: URL, book, podcast, article, video, GitHub repo, Reddit thread, PDF, quote, or raw idea. Trigger on "add", "save", "capture", "note this", "take notes on", or any request to record content in the knowledge base.
Add tweets to the Second Brain. Use when the user provides a Twitter/X URL and pasted tweet content, asking to "add a tweet", "save this tweet", or "capture this tweet".
Query your Second Brain with keyword search. Use when asked to "ask my notes", "what do I know about", "query my knowledge", "/ask", or when the user has a question that their notes might answer.
Create Obsidian templates for the Second Brain vault. Use when asked to "create a template", "make a template for", "add an Obsidian template", or "template for X".
Create or update today's private journal entry. Use when asked to "daily note", "journal", "log today", "morning pages", or "capture thoughts".