mermaid-diagram-generator

Mermaid Diagram Generator Skill

Purpose

This skill automatically converts text descriptions of system architectures, module specifications, workflow documentation, and design concepts into valid Mermaid diagram syntax. It enables clear visual communication of complex systems, ensuring diagrams are production-ready and embeddable in markdown documentation.

When to Use This Skill

Architecture Visualization: Convert architecture descriptions into flowcharts or block diagrams
Module Relationships: Create diagrams showing how brick modules connect via their studs (public contracts)
Workflow Documentation: Visualize workflow states, decisions, and transitions (DDD phases, investigation stages)
System Design: Display system components, data flow, and interactions
Sequence Diagrams: Show agent interactions, request/response patterns, or call sequences
Class Hierarchies: Document module structure and class relationships
State Machines: Model workflow states and valid transitions
Entity Relationships: Display data model structures and relationships
Timeline Planning: Create Gantt charts for project phases or milestones

Supported Diagram Types

Flowcharts (Default)

Best for: workflow sequences, decision trees, process flows, module relationships

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

Sequence Diagrams

Best for: agent interactions, API calls, multi-step processes, request/response patterns

sequenceDiagram participant User participant API participant Service User->>API: Request API->>Service: Process Service-->>API: Response API-->>User: Result

Class Diagrams

Best for: module structure, inheritance hierarchies, data models, component relationships

classDiagram class Brick { +String responsibility +PublicContract studs } class Module { +init() +process() } Brick <|-- Module

State Diagrams

Best for: workflow states, state machines, workflow phases, condition-based transitions

stateDiagram-v2 [] --> Planning Planning --> Design Design --> Implementation Implementation --> Testing Testing --> []

Entity Relationship Diagrams

Best for: data models, database schemas, entity relationships

erDiagram MODULE ||--o{ FUNCTION : exports MODULE ||--o{ DEPENDENCY : requires FUNCTION }o--|| CONTRACT : implements

Gantt Charts

Best for: project timelines, workflow phases, milestone planning

gantt title Project Timeline section Phase 1 Planning :p1, 0, 30d Design :p2, after p1, 20d section Phase 2 Implementation :p3, after p2, 40d Testing :p4, after p3, 25d

Step-by-Step Generation Process

Step 1: Understand the Source Material

Read the architecture description, spec, or workflow document
Identify the main entities or nodes
Determine how they relate or flow
Choose the appropriate diagram type

Step 2: Identify Diagram Type

Source Material Best Diagram Type

Workflow steps, process flow Flowchart

Module relationships, brick connections Flowchart or Class Diagram

Agent interactions, call sequences Sequence Diagram

States and transitions State Diagram

Data models, entities Class Diagram or ERD

Database schema ERD

Project timeline Gantt Chart

Complex hierarchies Class Diagram

Step 3: Extract Entities and Relationships

List all nodes/entities from the source
Identify connections between them
Determine connection types (data flow, inheritance, calling, etc.)
Note any decision points or conditions

Step 4: Generate Mermaid Syntax

Use appropriate Mermaid diagram declaration
Create nodes with descriptive labels
Draw connections with proper syntax
Add styling if needed for clarity
Ensure valid Mermaid syntax

Step 5: Validate and Enhance

Ensure all entities are included
Verify connections are accurate
Add styling for important elements
Make diagram readable and not cluttered
Test syntax for validity

Step 6: Document and Embed

Add title and description
Include explanation of diagram
Provide legend if needed
Embed in markdown with proper formatting

Usage Examples

Example 1: Architecture Description to Flowchart

Input:

The authentication module handles JWT token validation. When a request arrives, it first checks if a token exists. If not, it returns unauthorized. If it does, it validates the token signature. If valid, it extracts the payload and continues. If invalid, it returns forbidden. The payload is passed to the authorization module for role-based access control.

Output:

flowchart TD A[Request Arrives] --> B{Token Exists?} B -->|No| C[Return Unauthorized] B -->|Yes| D{Token Valid?} D -->|No| E[Return Forbidden] D -->|Yes| F[Extract Payload] F --> G[Check Role-Based Access] G --> H{Authorized?} H -->|No| I[Return Access Denied] H -->|Yes| J[Allow Request] C --> K[End] E --> K I --> K J --> K

Example 2: Module Spec to Class Diagram

Input:

Module: authentication

Exports: validate_token, TokenPayload, AuthError
Classes: TokenPayload (user_id, role, expires_at), AuthError (message, code)
Functions: validate_token(token, secret) -> TokenPayload
Internal: JWT (PyJWT library), Models (TokenPayload)

Output:

classDiagram class AuthenticationModule { +validate_token(token, secret) +TokenPayload +AuthError } class TokenPayload { +String user_id +String role +DateTime expires_at +to_dict() } class AuthError { +String message +Integer code +str() } AuthenticationModule -- TokenPayload AuthenticationModule -- AuthError

Example 3: Workflow to State Diagram

Input:

DDD Workflow: Phase 0 (Planning) -> Phase 1 (Documentation) -> Approval Gate -> Phase 2 (Code Planning) -> Phase 3 (Implementation) -> Phase 4 (Testing & Cleanup) -> Complete

Output:

stateDiagram-v2 [] --> Planning Planning --> Documentation Documentation --> ApprovalGate ApprovalGate --> CodePlanning CodePlanning --> Implementation Implementation --> Testing Testing --> []

Example 4: Agent Interaction to Sequence Diagram

Input:

The prompt-writer agent clarifies requirements from the user. It then sends the clarified requirements to the architect agent. The architect creates a specification and sends it to the builder agent. The builder implements code and sends it to the reviewer. The reviewer checks quality and sends feedback back to the builder if issues are found, or to the user if complete.

Output:

sequenceDiagram actor User participant PromptWriter participant Architect participant Builder participant Reviewer

User->>PromptWriter: Request Feature
PromptWriter->>Architect: Clarified Requirements
Architect->>Builder: Specification
Builder->>Reviewer: Implementation
Reviewer-->>Builder: Issues Found
Builder->>Reviewer: Fixed Implementation
Reviewer-->>User: Complete &#x26; Approved

Example 5: System Architecture to Flowchart

Input:

Client requests flow through API Gateway to Services. Services can be Authentication Service, User Service, or Data Service. All services connect to a shared Database and Logger. Services return responses through the API Gateway back to Client.

Output:

flowchart LR Client[Client] Gateway[API Gateway] Auth[Auth Service] User[User Service] Data[Data Service] DB[(Database)] Logger[Logger]

Client &#x3C;--> Gateway
Gateway --> Auth
Gateway --> User
Gateway --> Data
Auth --> DB
User --> DB
Data --> DB
Auth --> Logger
User --> Logger
Data --> Logger

Mermaid Syntax Reference

Flowchart Nodes

A[Rectangle] B(Rounded Rectangle) C{Diamond/Decision} D[(Database)] E[/Parallelogram Right/] F[\Parallelogram Left] G[[Subroutine]] H((Circle))

Flowchart Connections

A --> B # Arrow A -- Text --> B # Arrow with label A ---|Yes| B # Arrow with yes/no A -->|Condition| B A -.-> B # Dotted line A ==> B # Bold arrow

Styling

classDef className fill:#f9f,stroke:#333,stroke-width:2px,color:#000 class A,B className style A fill:#f9f,stroke:#333,stroke-width:4px

Quality Checklist

Before presenting a diagram, verify:

All entities from source are included
Connections accurately represent relationships
Diagram type matches content (flowchart for flows, sequence for interactions, etc.)
Labels are clear and descriptive
No circular logic or dead ends (unless intentional)
Mermaid syntax is valid
Diagram is readable and not overly complex
Decision points have clear yes/no paths
Legend provided if needed for understanding
Comments explain non-obvious elements

Common Patterns

Brick Module Visualization

flowchart TD B1["Brick Module 1<br/>(Responsibility)"] B2["Brick Module 2<br/>(Responsibility)"] S1["Stud: public_function"] S2["Stud: public_class"]

B1 --> S1
B1 --> S2
S1 -.depends on.-> B2
B2 --> "Stud: get_data"

Workflow Decision Tree

flowchart TD Start[Start] --> Q1{Condition 1?} Q1 -->|No| End1[End: Rejected] Q1 -->|Yes| Q2{Condition 2?} Q2 -->|No| End2[End: Review] Q2 -->|Yes| Q3{Condition 3?} Q3 -->|No| End3[End: Partial] Q3 -->|Yes| End4[End: Approved]

Error Handling Flow

flowchart TD A[Execute] --> B{Error?} B -->|No| C[Success] B -->|Yes| D{Recoverable?} D -->|No| E[Fail] D -->|Yes| F[Retry] F --> A C --> G[End] E --> G

Integration with Documentation

Embedding in Markdown

System Architecture

flowchart TD
    ...

Key Components:

Component A handles...
Component B processes...

Using with Document-Driven Development

Create diagrams during documentation phase
Include architecture diagrams in spec docs
Use sequence diagrams to explain workflows
Add state diagrams to describe state machines

Using with Investigation Workflow

Visualize discovered architecture
Show data flow between components
Map discovered dependencies
Display call sequences between services

Tips for Effective Diagrams

Keep It Simple: One concept per diagram
Use Clear Labels: Names should describe purpose
Follow Visual Conventions: Diamonds for decisions, circles for states
Avoid Crossing Lines: Reorganize to reduce visual clutter
Logical Flow: Top-to-bottom or left-to-right
Consistent Styling: Similar elements should look similar
Legend: Include if symbols aren't obvious
Test Syntax: Ensure Mermaid renders without errors
Add Comments: Explain non-obvious relationships
Iterate: Refine based on feedback

Common Pitfalls to Avoid

Too Complex: Diagram has too many elements (break into multiple diagrams)
Unclear Labels: Node names don't describe their purpose
Missing Connections: Important relationships not shown
Invalid Syntax: Mermaid errors prevent rendering
Ambiguous Decision Points: Yes/no paths not clearly marked
Crossing Arrows: Visual confusion from overlapping connections
No Legend: Symbols or colors not explained
Wrong Diagram Type: Using flowchart for sequence data
Inconsistent Style: Different formatting for similar elements
No Context: Diagram shown without explanation

Success Criteria

A good Mermaid diagram:

Related Skills

module-spec-generator: Generate specs that can be visualized as class diagrams
Document-Driven Development: Use diagrams in specification documents
Investigation Workflow: Create architecture diagrams from discovered systems

Output Format

Diagrams are generated in Mermaid markdown format, ready to embed:

    ```mermaid
    [Generated Mermaid Syntax]
    ```

Include explanation before or after the diagram.

Feedback and Improvement

This skill evolves based on usage patterns:

- What types of diagrams are most useful?

- What features make diagrams clearer?

- What errors occur and how to prevent them?

- How can diagrams better support documentation?

Document learnings and suggest improvements for ~/.amplihack/.claude/context/DISCOVERIES.md
.