mermaid-gen

仓库: vladm3105/aidoc-flow-framework
安装量: 69
排名: #11151

安装

npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill mermaid-gen

mermaid-gen Purpose

The mermaid-gen skill provides AI assistants with expert guidance for creating syntactically correct Mermaid diagrams while avoiding common parsing errors that cause rendering failures. This skill focuses on diagram syntax correctness and best practices.

Key Benefits:

Error Prevention: Avoid nested quotes, special character issues, and malformed syntax Syntax Mastery: Apply correct patterns for flowcharts, sequence diagrams, state machines, etc. Quality Assurance: Validate diagrams before rendering using proven templates Troubleshooting: Diagnose and fix parse errors systematically Best Practices: Follow standardized naming, styling, and structure conventions When to Use This Skill

Use mermaid-gen when:

Creating new Mermaid diagrams (flowcharts, sequence diagrams, state machines, etc.) Fixing parse errors or rendering issues in existing diagrams Converting written descriptions into Mermaid syntax Validating diagram syntax before committing to documentation Debugging "Expecting X, got Y" parse errors Migrating diagrams from other formats to Mermaid Need best practice guidance for node naming, styling, subgraphs

Do NOT use mermaid-gen when:

Creating simple tables or text-based lists (use markdown tables) Need diagram file management or SVG generation (use charts-flow skill instead) Creating data visualization charts (bar, pie, line - use charting libraries) Need Gantt charts or Git graphs (outside core focus) Diagram is already working perfectly (no changes needed)

Relationship to charts-flow skill:

charts-flow: Manages diagram files, generates SVG, embeds in documents mermaid-gen: Ensures diagram syntax is correct before file creation Use together: charts-flow skill calls mermaid-gen for diagram generation Skill Inputs Required Inputs Input Description Example Diagram Type Type of Mermaid diagram flowchart, sequence, state, class Diagram Purpose What the diagram represents "Agent communication flow", "State machine transitions" Content Description Key elements and relationships "3 agents, 1 database, request/response flow" Optional Inputs Input Description Default Existing Code Current Mermaid code (if fixing) None (creating new) Error Message Parse error from renderer None Styling Preferences Color scheme, layout direction Project defaults Naming Convention Node ID format camelCase Skill Workflow

Follow this 5-step process to create or fix Mermaid diagrams:

Step 1: Understand Requirements Identify diagram type (flowchart, sequence, state, class, etc.) List all nodes/entities that need to be represented Identify relationships and connections Determine flow direction (TD, LR, etc.) Note any grouping needs (subgraphs) Step 2: Plan Node Structure Create meaningful node IDs (camelCase, no spaces) Keep display labels concise but descriptive Identify decision points (diamond shapes) Plan database/storage nodes (cylinder shapes) Determine which nodes need special shapes Step 3: Apply Syntax Rules (Critical) Remove nested quotes from all node labels Wrap multi-line labels (with
) in double quotes Keep edge labels simple - no quotes unless necessary Use ID/label syntax for subgraphs with special characters Separate node IDs from labels: NodeID[Display Label] Step 4: Build Diagram with Template Start with appropriate template (flowchart, sequence, state) Add nodes with correct syntax Define relationships/edges with proper arrow types Group related nodes in subgraphs (if needed) Add styling directives AFTER all nodes defined Include comments (%%) for complex sections Step 5: Validate and Test Check for nested quotes in any labels Verify subgraph IDs match style references Confirm all node IDs are unique Test in Mermaid Live Editor (https://mermaid.live) Validate all relationships resolve correctly Ensure rendering succeeds without errors

Error Recovery: If parse error occurs, see "Troubleshooting Guide" section below.

Common Mermaid Syntax Errors & Solutions 1. Quotes in Node Labels

❌ WRONG - Nested quotes cause parse errors:

User[User: "What is the status?"] --> System Response["Message: "Success""] --> User

✅ CORRECT - Remove inner quotes or escape properly:

User[User: What is the status?] --> System Response["Message: Success"] --> User

Rule: Never use nested quotes within node labels enclosed in [] or (). Either:

Remove the inner quotes entirely Wrap the entire label in double quotes if using
tags 2. Multi-line Nodes with Special Characters

❌ WRONG - Decimals and special chars without quotes:

Results[Top Results:
1. system_arch.md (0.89)
2. safety.yaml (0.84)]

✅ CORRECT - Wrap in double quotes when using with numbers/decimals:

Results["Top Results:
1. system_arch.md (0.89)
2. safety.yaml (0.84)"]

Rule: When node labels contain:


tags AND decimal numbers
tags AND special characters Multiple lines with complex content

Wrap the ENTIRE label in double quotes: NodeID["label content"]

  1. Edge Labels with Quotes

❌ WRONG - Quotes in edge labels:

A -->|"Execute"| B A -->|"Cancel" or Timeout| C

✅ CORRECT - Remove quotes from edge labels:

A -->|Execute| B A -->|Cancel or Timeout| C

Rule: Edge labels (text between |...|) should never contain quotes unless absolutely necessary. Use plain text.

  1. Subgraph Names with Special Characters in Style Directives

❌ WRONG - Ampersands and special chars in style references:

subgraph "Audit & Compliance" Node1 end style Audit & Compliance fill:#fff

✅ CORRECT - Use ID/label syntax for subgraphs:

subgraph AuditCompliance["Audit & Compliance"] Node1 end style AuditCompliance fill:#fff

Rule: When applying styles to subgraphs with special characters:

Give subgraph an ID without special chars: subgraph ID["Display Name"] Reference the ID in style directive: style ID fill:#color 5. Node IDs vs Display Labels

✅ CORRECT - Separate IDs from labels:

UserNode[User: Query the system] --> ProcessNode[Processing Service] ProcessNode --> DBNode[(Database)]

Rule:

First part (before [) is the node ID (no spaces, use camelCase) Content in [] is the display label (can have spaces, special chars when quoted) Mermaid Chart Templates Flowchart Template (Architecture Diagrams) flowchart TD %% Define nodes with clear IDs and labels User[User Input] -->|Action| Service[Processing Service
FastAPI]

Service -->|Validate| Validator{Validation Check}
Validator -->|Invalid| ErrorNode["Error Response<br/>Status: 400"]
Validator -->|Valid| Database[(Database<br/>PostgreSQL)]

Database -->|Query Result| Transform[Transform Data]
Transform -->|Response| User

%% Group related components
subgraph Backend["Backend Services"]
    Service
    Validator
    Transform
end

subgraph Storage["Data Storage"]
    Database
end

%% Apply styles AFTER all nodes defined
style User fill:#e1f5ff
style Backend fill:#f0f0f0
style Storage fill:#fff4e1

Sequence Diagram Template sequenceDiagram participant User participant API as API Gateway participant Auth as Auth Service participant DB as Database

User->>API: Request with credentials
API->>Auth: Validate token
Auth-->>API: Token valid
API->>DB: Query data
DB-->>API: Return results
API-->>User: Success response

Note over User,DB: All communication encrypted via TLS

State Diagram Template stateDiagram-v2 [] --> Idle Idle --> Processing: Start request Processing --> Success: Complete Processing --> Failed: Error occurs Success --> [] Failed --> Retry: Auto retry Retry --> Processing: Attempt again Failed --> [*]: Max retries exceeded

Quality Gates (Definition of Done) Syntax Validation Gates No nested quotes: All node labels checked for nested quote issues Multi-line syntax: Labels with
wrapped in double quotes Edge labels clean: No unnecessary quotes in edge labels (between |...|) Subgraph IDs valid: Subgraphs with special chars use ID/label syntax Node IDs unique: No duplicate node IDs in diagram Node ID format: All IDs use camelCase with no spaces Structure Validation Gates Diagram renders: Successfully renders in Mermaid Live Editor All relationships resolve: No broken node references Flow direction correct: TD, LR, RL, BT specified appropriately Subgraphs organized: Related nodes grouped logically Styling applied: Style directives added AFTER all nodes defined Quality Assurance Gates Labels concise: Display labels descriptive but not verbose Comments added: Complex sections documented with %% comments Appropriate diagram type: Using correct type (flowchart vs sequence vs state) Visual clarity: Diagram is readable and understandable Documentation integration: Title/caption added if embedding in docs Pre-Commit Validation Parse errors: Zero parse errors in renderer Cross-browser: Renders correctly in GitHub, VS Code, docs site File size: Diagram complexity reasonable (not overly complex) Standards compliance: Follows project diagram naming conventions Skill Constraints What NOT to Do Do NOT use nested quotes in any node labels (causes parse errors) Do NOT put quotes in edge labels unless absolutely necessary Do NOT use special characters in subgraph IDs without ID/label syntax Do NOT reference subgraph display names in style directives (use IDs) Do NOT add styling directives before all nodes are defined Do NOT use literal newlines in labels (use
tags instead) Do NOT create overly complex diagrams (>50 nodes - split into multiple) Do NOT use generic node IDs like node1, node2 (use descriptive IDs) Do NOT skip validation in Mermaid Live Editor before committing Do NOT use deprecated Mermaid syntax (check version compatibility) Diagram Type Restrictions Do NOT use Mermaid for: Data visualization charts (bar, pie, line charts - use charting library) Gantt charts for project management (use dedicated PM tools) Git graphs (use git visualization tools) Organizational charts with photos (use org chart tools) Complex data tables (use markdown tables) File Organization Rules Always validate syntax before creating diagram files Always use templates as starting point for diagram type Always test in Mermaid Live Editor before embedding Always include diagram type in filename or documentation Always follow project naming conventions for node IDs Example Usage Example 1: Create New Flowchart

User Request:

"Create a flowchart showing the authentication flow: user submits credentials, system validates, checks database, returns token or error"

Skill Actions:

Identify type: Flowchart (process flow with decisions) Plan nodes: User, Validator, Database, TokenService, Error, Success Plan flow: User → Validate → Decision → Database OR Error → Success OR Error Apply syntax rules: Node IDs: userInput, validator, dbCheck, tokenService, errorResponse, successResponse Remove nested quotes from all labels Use decision diamond for validation check Build from template: Use Flowchart Template Validate: Test in Mermaid Live Editor

Result:

flowchart TD userInput[User: Submit Credentials] -->|POST /auth| validator{Validate Format} validator -->|Invalid| errorResponse["Error Response
Status: 400"] validator -->|Valid| dbCheck[(Database
Verify User)] dbCheck -->|Not Found| errorResponse dbCheck -->|Found| tokenService[Generate JWT Token] tokenService -->|Return| successResponse["Success Response
Token + Expiry"]

Example 2: Fix Parse Error

User Request:

"My sequence diagram won't render. Error: 'Expecting SQE, got STR'. Here's the code: User->>API: Request "data""

Skill Actions:

Diagnose error: "Expecting SQE, got STR" = nested quotes issue Locate problem: Edge label has nested quotes: Request "data" Apply fix: Remove inner quotes: Request data Validate: Test corrected syntax in Mermaid Live Editor Return fixed code

Result:

sequenceDiagram User->>API: Request data API-->>User: Response

Explanation: Edge labels between |...| or after : should not contain quotes.

Example 3: Create State Machine with Complex Labels

User Request:

"Create a state diagram for order processing: Draft → Submitted → Processing → Completed or Failed. Include transition conditions."

Skill Actions:

Identify type: State diagram (state transitions) Plan states: Draft, Submitted, Processing, Completed, Failed Plan transitions: With labeled conditions Apply syntax rules: Use stateDiagram-v2 syntax State IDs: Draft, Submitted, Processing, Completed, Failed Transition labels with conditions (no quotes) Build from template: Use State Diagram Template Validate: Test in Mermaid Live Editor

Result:

stateDiagram-v2 [] --> Draft Draft --> Submitted: User clicks Submit Submitted --> Processing: Payment verified Processing --> Completed: All items shipped Processing --> Failed: Payment declined Completed --> [] Failed --> Draft: Retry allowed Failed --> [*]: Max retries exceeded

Common Patterns Decision Flow Pattern flowchart TD Input[Receive Input] --> Validate{Validate Input} Validate -->|Invalid| Reject["Reject with Error
Return 400"] Validate -->|Valid| Process[Process Request] Process --> Output[Return Success]

Multi-Source Integration Pattern flowchart TD User[User Query] --> Router{Query Router}

Router -->|Database| SQL[SQL Connector]
Router -->|Cache| Redis[Redis Connector]
Router -->|API| External[External API]

SQL --> Merge[Merge Results]
Redis --> Merge
External --> Merge

Merge --> Response[Formatted Response]
Response --> User

Error Handling Pattern flowchart TD Start[Start Process] --> Try{Execute} Try -->|Success| Complete[Complete Successfully] Try -->|Error| Retry{Retry Count < 3?} Retry -->|Yes| Wait[Exponential Backoff] Wait --> Try Retry -->|No| Failed["Failed
Log and Alert"]

Troubleshooting Guide Error: "Expecting 'SQE', got 'STR'" Cause: Nested quotes in node labels Fix: Remove inner quotes or wrap entire label in quotes Error: "Expecting 'SPACE', got 'AMP'" Cause: Special character (&, /, etc.) in style directive Fix: Use subgraph ID/label syntax: subgraph ID["Name"] Error: "Parse error on line X" Cause: Usually quote-related or malformed syntax Fix: Check for nested quotes, verify node/edge syntax Chart not rendering Cause: Invalid node IDs, broken references, or syntax errors Fix: Validate in Mermaid Live Editor, check node ID consistency Examples from Real Documentation Architecture Flow (ADR Pattern) flowchart TD User[User: Submit command] -->|1. Classify| Detector{Command Detector
GPT-4 + Rules}

Detector -->|Query| QueryPath[Execute Immediately]
Detector -->|Command| SafetyPath[Safety Validation]

SafetyPath -->|Check| Circuit{Circuit Breaker Status}
Circuit -->|Active| Block["Block Command<br/>Display Reason"]
Circuit -->|Inactive| Execute[Execute Command]

Execute -->|Log| Audit[WORM Audit Storage]
Execute -->|Response| User

subgraph SafetyControls["Safety Controls"]
    Detector
    Circuit
    Audit
end

style User fill:#e1f5ff
style SafetyControls fill:#fff4e1

Data Pipeline Flow flowchart LR Source[Data Source] -->|Ingest| Process[Processing Pipeline]

Process -->|Transform| Transform[Transform Layer<br/>Validate & Clean]
Transform -->|Load| Storage[(Data Warehouse)]

Storage -->|Query| Analytics[Analytics Service]
Analytics -->|Visualize| Dashboard[Dashboard UI]

subgraph Pipeline["Data Pipeline"]
    Process
    Transform
end

style Pipeline fill:#f0f0f0

Quick Reference Card Element Syntax Example Node (rectangle) ID[Label] Node1[Process Data] Node (rounded) ID(Label) Start(Begin Process) Node (database) ID[(Label)] DB[(PostgreSQL)] Node (circle) ID((Label)) Point((A)) Decision ID{Label} Check{Is Valid?} Arrow --> A --> B Labeled arrow -- text --> or `--> text Subgraph subgraph ID["Label"] subgraph Sys["System"] Style style ID fill:#color style Node1 fill:#e1f5ff Comment %% comment %% This is a note Line break
in label Node["Line 1
Line 2"] Output Format Generated Artifacts

When using the mermaid-gen skill, the primary output is:

Mermaid Diagram Code Block:

Format: Markdown code block with mermaid language identifier Content: Syntactically valid Mermaid diagram code Validation: Tested in Mermaid Live Editor before delivery Structure: Includes comments, styling, and proper node/edge syntax

Example Output:

flowchart TD
    %% Define nodes
    Start[Start Process] --> Process[Execute Task]
    Process --> End[Complete]

    %% Apply styling
    style Start fill:#e1f5ff
    style End fill:#c8e6c9

Integration with charts-flow Skill

Skill Relationship:

mermaid-gen: Creates syntactically correct diagram code charts-flow: Takes diagram code and manages file creation, SVG generation, document embedding

Typical Workflow:

User requests diagram for documentation charts-flow skill invoked for file management charts-flow internally calls mermaid-gen for diagram generation mermaid-gen returns validated Mermaid code charts-flow creates diagram file, generates SVG, embeds in parent document

Standalone Usage: When user only needs diagram code (not file management):

Invoke mermaid-gen directly Returns diagram code block User manually embeds in documentation

Combined Usage: When user needs complete diagram file workflow:

Invoke charts-flow skill (which uses mermaid-gen internally) Returns diagram file + SVG + parent document updates Output Validation Checklist

Every output from mermaid-gen must meet these criteria:

✅ Renders without errors in Mermaid Live Editor ✅ No nested quotes in any labels ✅ Subgraph IDs match style references ✅ All node IDs are unique ✅ Comments explain complex sections ✅ Follows project naming conventions Integration with Project Workflow Relationship to Other Skills

charts-flow Skill:

Purpose: Diagram file management, SVG generation, document embedding Integration: Calls mermaid-gen to generate diagram content Use Case: Creating separate diagram files in diagrams/ subdirectories

doc-flow Skill:

Purpose: Specification-Driven Development workflow (BRD → PRD → ADR → SYS → SPEC) Integration: Diagrams created with mermaid-gen support ADRs, SYS docs, and architecture specifications Use Case: Adding architecture diagrams to ADR documents or system specifications

project-mngt Skill:

Purpose: MVP/MMP/MMR implementation planning Integration: Diagrams visualize project dependencies and implementation flows Use Case: Creating Gantt-style timelines or dependency graphs (if supported by Mermaid) Documentation Standards Alignment

Technical Guidelines (per CLAUDE.md):

Focus on technical implementation (not marketing language) Cost optimization considerations (lightweight SVG format) Performance focus (separate diagram files for faster rendering) Security considerations (no executable code in diagrams)

Best Practice Integration:

Use mermaid-gen for syntax correctness Use charts-flow for file management and performance optimization Follow project naming conventions for node IDs Validate all diagrams before committing to version control Version Version: 1.0 Last Updated: 2025-11-05 Lessons Learned From: ADR Architecture Flow diagram fixes Related Documentation Mermaid Official Docs Mermaid Live Editor GitHub Mermaid Support

← 返回排行榜