| name | github:mermaid-diagram |
| description | Generate GitHub-compatible Mermaid diagrams. Enforces GitHub rendering constraints (supported types, <br/> for line breaks, label quoting). Invokable with /github:mermaid-diagram or /mermaid.
|
| tools | ["Read","Write","Glob","Grep","Bash"] |
| hooks | {"PostToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"python3 $SKILL_DIR/scripts/validate-mermaid.py"}]}]} |
Mermaid Diagram Generator — GitHub-Compatible
Generates Mermaid diagrams that render correctly in GitHub Issues, PRs, Discussions, Wikis, and Markdown files.
GitHub Constraints (MANDATORY)
These rules apply to all diagrams generated by this skill:
1. Supported Diagram Types Only
GitHub renders a fixed set of Mermaid diagram types. Use only:
| Type | Keyword |
|---|
| Flowchart | flowchart TD / flowchart LR |
| Graph | graph TB / graph TD / graph LR |
| Sequence | sequenceDiagram |
| Class | classDiagram |
| State | stateDiagram-v2 |
| Entity-Relationship | erDiagram |
| Gantt | gantt |
| Pie | pie |
| Git graph | gitGraph |
| Mindmap | mindmap |
| Quadrant | quadrantChart |
| XY Chart | xychart-beta |
Do NOT use diagram types outside this list — they will not render on GitHub.
2. Line Breaks in Labels
- NEVER use
inside node labels — GitHub's Mermaid parser treats it as a literal escape and breaks parsing.
- ALWAYS use
<br/> for multi-line labels in graph and flowchart diagrams.
✓ CF[CloudFront<br/>Distribution]
✗ CF[CloudFront
Distribution] ← parse error on GitHub
3. Special Characters in Labels
Wrap labels containing special characters ((, ), {, }, ", :) in double quotes:
✓ A["POST /api/resource"]
✓ B["User (authenticated)"]
✗ A[POST /api/resource] ← may break parsing
4. No Third-Party Init Directives
Avoid %%{init: {...}}%% theme overrides — GitHub enforces its own Mermaid version and renderer. Theme overrides may cause parse errors or be silently ignored.
5. Label Length
Max 4–5 words per label. Verbose labels cause layout overflow and are harder to read.
Diagram Types
Flowchart
Best for: decision trees, process flows, algorithm explanations.
flowchart TD
Start[Process Begins] --> Decision{Condition?}
Decision -->|Yes| ActionA[Execute A]
Decision -->|No| ActionB[Execute B]
ActionA --> End[Complete]
ActionB --> End
Directions: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
Node shapes:
[Rectangle] — standard step
(Rounded) — process/action
([Stadium]) — start/end
[(Database)] — cylinder/storage
((Circle)) — connection point
{Diamond} — decision
{{Hexagon}} — preparation
[/Parallelogram/] — input/output
Connection types:
--> solid arrow
--- solid line (no arrow)
-.-> dashed arrow
==> thick arrow
-->|Label| labelled arrow
Sequence Diagram
Best for: API interactions, service communication, request/response flows.
sequenceDiagram
participant Client
participant Server
participant DB
Client->>Server: POST /api/resource
Server->>DB: Query records
DB-->>Server: Return results
Server-->>Client: 200 OK
Arrow types:
->> solid (request)
-->> dashed (response)
-x cross (failed)
-) async message
Blocks: loop, alt/else, opt, par/and, Note over
Graph (Architecture / C4)
Best for: system architecture, component relationships, service dependencies.
graph TB
subgraph Frontend
UI[React App]
end
subgraph Backend
API[REST API]
Worker[Queue Worker]
end
DB[(DynamoDB)]
Cache[(ElastiCache)]
UI -->|HTTPS| API
API --> Worker
API --> DB
API --> Cache
Critical rules for graph / graph TB / graph TD:
- Use
<br/> for multi-line labels — causes parse errors on GitHub
- Labels: logical names only — no IDs, ARNs, PK/SK patterns, or schema detail
- Show containers/services only — not internal code structure
Entity-Relationship Diagram
Best for: data models, schema design, entity relationships.
erDiagram
USER {
string id PK
string email
string name
}
ORDER {
string id PK
string userId FK
string status
}
USER ||--o{ ORDER : "places"
State Diagram
Best for: state machines, lifecycle flows, status transitions.
stateDiagram-v2
[*] --> Pending
Pending --> InProgress : start
InProgress --> Done : complete
InProgress --> Failed : error
Failed --> Pending : retry
Done --> [*]
Styling
Let GitHub Handle Theme
GitHub applies its own Mermaid theme. Do not add project-specific inline colors.
✓ Correct — no inline styles:
flowchart TD
Start[Begin] --> Check{Valid?}
Check -->|Yes| Success[Complete]
Check -->|No| Error[Handle Error]
Emphasis Styling (use sparingly)
Only add inline styles to highlight nodes that must stand out:
flowchart TD
Normal[Regular Step] --> Critical[Key Decision]
Critical -->|Fail| ErrorState[Error]
Critical -->|Pass| Done[Done]
style Critical stroke-width:3px
style ErrorState fill:#4a1515,stroke:#ef4444
style Done fill:#154a15,stroke:#22c55e
Allowed emphasis styles:
stroke-width:3px — critical/new nodesfill:#4a1515,stroke:#ef4444 — error/failure (red tint)fill:#154a15,stroke:#22c55e — success/healthy (green tint)fill:#4a4115,stroke:#eab308 — warning (yellow tint)
Rule: Style max 3–4 nodes per diagram. Everything else inherits GitHub theme.
Complexity Limits
| Limit | Value |
|---|
| Max nodes per diagram | 25 |
| Max flowchart depth | 7 levels |
| Max sequence interactions | 10 |
If diagram exceeds limits: split into multiple diagrams (overview + detail) or use subgraphs to group.
Workflow
When asked to create a diagram:
- Identify type — flowchart, sequence, graph, ERD, state, or other?
- Choose direction — TD for processes, LR for timelines/pipelines, TB for architecture
- Draft structure — keep under 25 nodes
- Apply GitHub constraints —
<br/> not , quote special chars, supported type only
- Add emphasis sparingly — only nodes that need to stand out
- Write to file —
.mmd extension (e.g., docs/stories/{id}/design/c4-container.mmd)
Common Patterns
Architecture (C4 Container)
graph TB
User[Browser / Mobile]
subgraph AWS
CF[CloudFront<br/>CDN]
API[API Gateway]
Lambda[Lambda<br/>Handler]
DB[(DynamoDB)]
S3[(S3 Bucket)]
end
User -->|HTTPS| CF
CF --> API
API --> Lambda
Lambda --> DB
Lambda --> S3
style Lambda stroke-width:3px
API Request Flow (Sequence)
sequenceDiagram
participant Client
participant Gateway
participant Auth
participant Service
participant DB
Client->>Gateway: POST /api/resource
Gateway->>Auth: Validate JWT
alt Token valid
Auth-->>Gateway: Authorized
Gateway->>Service: Process
Service->>DB: Write record
DB-->>Service: OK
Service-->>Gateway: 201 Created
Gateway-->>Client: 201 Created
else Token invalid
Auth-->>Gateway: Rejected
Gateway-->>Client: 401 Unauthorized
end
Business Process Flow
flowchart TD
Start([User Submits PR]) --> Lint{Lint Pass?}
Lint -->|No| NotifyDev[Notify Developer]
Lint -->|Yes| Tests{Tests Pass?}
Tests -->|No| NotifyDev
Tests -->|Yes| Review[Request Review]
Review --> Approved{Approved?}
Approved -->|No| Changes[Request Changes]
Approved -->|Yes| Merge[Merge to Main]
Changes --> Start
style Lint stroke-width:3px
style Tests stroke-width:3px
style NotifyDev fill:#4a1515,stroke:#ef4444
style Merge fill:#154a15,stroke:#22c55e
Data Model (ERD)
erDiagram
USER {
string id PK
string email
string name
string role
}
STORY {
string id PK
string userId FK
string title
string status
}
COMMENT {
string id PK
string storyId FK
string userId FK
string body
}
USER ||--o{ STORY : "creates"
USER ||--o{ COMMENT : "writes"
STORY ||--o{ COMMENT : "has"
Validation
After generating a diagram, verify:
