MermaidJS Diagrams Skill

Generate MermaidJS diagrams as fenced code blocks in Markdown. Diagrams render natively in GitHub, VS Code, Obsidian, and most modern Markdown viewers — no external tooling required.

Supported Diagram Types

Type	MermaidJS syntax	Use case
Flowchart	flowchart TD	Logic flows, decision trees, process maps
Sequence diagram	sequenceDiagram	API calls, service interactions, message flows
Class diagram	classDiagram	Domain models, OOP structures
Entity-relationship	erDiagram	Database schemas
State diagram	stateDiagram-v2	State machines, lifecycles
C4 context	C4Context	System architecture overviews

For official syntax documentation for each type, see references/diagram-types.md.

Workflow

1. Understand the Diagram

Ask one question at a time to clarify what to draw. Do not ask multiple questions at once.

If the user's request is already specific enough (e.g. "sequence diagram of the login flow between client, API, and database"), skip clarification and generate immediately.

Focus on:

• What is being shown — process, system, data model, state machine?
• Who the actors/components are — services, classes, entities, states?
• Key relationships or steps — what connects to what, in what order?

2. Choose the Right Diagram Type

Select the most appropriate type based on what the user wants to show:

• Flowchart — when there are decisions, branches, or sequential steps
• Sequence — when timing and order of messages between actors matters
• Class — when showing attributes, methods, and inheritance relationships
• ER — when showing database tables and their relationships
• State — when an entity moves through distinct states based on events
• C4 Context — when showing a system and its external dependencies at a high level

If the user specifies a type, use that type. If it would not render well, offer a better alternative with a brief explanation.

3. Generate the Diagram

Produce the Mermaid code block. Follow the validation checklist before presenting:

Validation checklist:

• All arrows use correct syntax for the type (-->, ->>, -->|label|, etc.)
• Node/participant identifiers are spelled consistently throughout (implicit declaration on first use is valid)
• Brackets and quotes are balanced and closed
• No reserved keywords used as unquoted node labels
• Direction specified for flowcharts (TD, LR, BT, RL)
• Edge labels with special characters (e.g. <, >, ") are wrapped in quotes; plain text labels between |...| do not need quoting

Present the diagram inline in the conversation as a fenced code block:

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do thing]
    B -->|No| D[Do other thing]
```

Then ask: "Does this look right? I can adjust the layout, add more detail, or embed this in a file."

4. Embed or Save (Confirmation Required)

If the user wants the diagram saved, offer two options:

Option	Action
Embed in existing file	Insert the fenced block at an appropriate location in the file
Create new file	Write to docs/diagrams/<topic>.md with a short heading

Write operations require explicit confirmation:

Operation	Confirmation prompt
Embed in existing file	"Embed this diagram in <file path>?"
Create new diagram file	"Write this to docs/diagrams/<topic>.md?"

When creating a new file:

• Create docs/diagrams/ if it does not exist
• If docs/diagrams/<topic>.md already exists, do not overwrite silently — ask: "That file already exists. Replace it, or choose a different filename?"

Only proceed after the user confirms.

Integration with Brainstorming Skill

When the Brainstorming skill produces a spec in docs/specs/, offer to generate diagrams for:

• Architecture sections → C4 context or flowchart
• Data model sections → ER diagram or class diagram
• Interaction flows → sequence diagram
• State lifecycle sections → state diagram

Example offer:

"The spec covers a request flow between three services — want me to add a sequence diagram for that section?"

Error Handling

Diagram does not render (syntax error): Re-read the validation checklist, correct the specific issue, and present the fixed version.

User says layout is wrong: For flowcharts, try a different direction keyword (TD, LR, BT, RL). For class and state diagrams, a direction statement (direction LR, etc.) can be added. Sequence and C4 diagrams do not support layout direction overrides.

Diagram is too large to read: Break it into multiple smaller diagrams focused on sub-systems, or use subgraphs to group related nodes.

C4 diagrams do not render in all viewers: Mermaid's C4 support uses C4Context as the diagram keyword with Person(), System(), and Rel() macros — no @ prefix. GitHub and VS Code render C4 correctly; some other viewers do not. If the user's target viewer does not support C4, offer a standard flowchart as a fallback.

Additional Resources

For official syntax documentation for each diagram type, see references/diagram-types.md.