mermaid-gen by vladm3105/aidoc-flow-framework
npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill mermaid-genmermaid-gen 技能为 AI 助手提供专家指导,用于创建语法正确的 Mermaid 图表,同时避免导致渲染失败的常见解析错误。此技能侧重于图表语法正确性和最佳实践。
主要优势:
在以下情况使用 mermaid-gen:
在以下情况不要使用 mermaid-gen:
charts-flow 技能代替)广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
与 charts-flow 技能的关系:
charts-flow:管理图表文件,生成 SVG,嵌入文档mermaid-gen:确保在文件创建前图表语法正确charts-flow 技能调用 mermaid-gen 来生成图表| 输入 | 描述 | 示例 |
|---|---|---|
| 图表类型 | Mermaid 图表的类型 | flowchart, sequence, state, class |
| 图表目的 | 图表所代表的内容 | "代理通信流程", "状态机转换" |
| 内容描述 | 关键元素和关系 | "3 个代理,1 个数据库,请求/响应流程" |
| 输入 | 描述 | 默认值 |
|---|---|---|
| 现有代码 | 当前的 Mermaid 代码(如果需要修复) | 无(创建新的) |
| 错误消息 | 来自渲染器的解析错误 | 无 |
| 样式偏好 | 配色方案,布局方向 | 项目默认值 |
| 命名约定 | 节点 ID 格式 | camelCase |
遵循这个 5 步流程来创建或修复 Mermaid 图表:
<br/>)用双引号包裹NodeID[显示标签]%%)错误恢复:如果发生解析错误,请参阅下面的"故障排除指南"部分。
❌ 错误 - 嵌套引号导致解析错误:
User[User: "What is the status?"] --> System
Response["Message: "Success""] --> User
✅ 正确 - 移除内部引号或正确转义:
User[User: What is the status?] --> System
Response["Message: Success"] --> User
规则: 切勿在包裹在 [] 或 () 中的节点标签内使用嵌套引号。可以:
<br/> 标签,则将整个标签用双引号包裹❌ 错误 - 没有引号的十进制数和特殊字符:
Results[Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)]
✅ 正确 - 当与数字/小数一起使用时,用双引号包裹:
Results["Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)"]
规则: 当节点标签包含:
<br/> 标签 和 十进制数字<br/> 标签 和 特殊字符将整个标签用双引号包裹:NodeID["标签内容"]
❌ 错误 - 边标签中的引号:
A -->|"Execute"| B
A -->|"Cancel" or Timeout| C
✅ 正确 - 从边标签中移除引号:
A -->|Execute| B
A -->|Cancel or Timeout| C
规则: 边标签(|...| 之间的文本)除非绝对必要,否则不应包含引号。使用纯文本。
❌ 错误 - 样式引用中的 & 符号和特殊字符:
subgraph "Audit & Compliance"
Node1
end
style Audit & Compliance fill:#fff
✅ 正确 - 对子图使用 ID/标签语法:
subgraph AuditCompliance["Audit & Compliance"]
Node1
end
style AuditCompliance fill:#fff
规则: 当对包含特殊字符的子图应用样式时:
subgraph ID["显示名称"]style ID fill:#color✅ 正确 - 将 ID 与标签分开:
UserNode[User: Query the system] --> ProcessNode[Processing Service]
ProcessNode --> DBNode[(Database)]
规则:
[ 之前)是节点 ID(无空格,使用 camelCase)[] 中的内容是显示标签(可以有空格,用引号包裹时可以有特殊字符)flowchart TD
%% Define nodes with clear IDs and labels
User[User Input] -->|Action| Service[Processing Service<br/>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
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
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
<br/> 的标签用双引号包裹|...| 之间)%% 注释记录<br/> 标签代替)node1、node2(使用描述性 ID)用户请求:
"创建一个显示认证流程的流程图:用户提交凭据,系统验证,检查数据库,返回令牌或错误"
技能操作:
userInput, validator, dbCheck, tokenService, errorResponse, successResponse结果:
flowchart TD
userInput[User: Submit Credentials] -->|POST /auth| validator{Validate Format}
validator -->|Invalid| errorResponse["Error Response<br/>Status: 400"]
validator -->|Valid| dbCheck[(Database<br/>Verify User)]
dbCheck -->|Not Found| errorResponse
dbCheck -->|Found| tokenService[Generate JWT Token]
tokenService -->|Return| successResponse["Success Response<br/>Token + Expiry"]
用户请求:
"我的序列图无法渲染。错误:'Expecting SQE, got STR'。这是代码:
User->>API: Request "data""
技能操作:
Request "data"Request data结果:
sequenceDiagram
User->>API: Request data
API-->>User: Response
解释:|...| 之间或 : 之后的边标签不应包含引号。
用户请求:
"为订单处理创建一个状态图:Draft → Submitted → Processing → Completed 或 Failed。包含转换条件。"
技能操作:
stateDiagram-v2 语法Draft, Submitted, Processing, Completed, Failed结果:
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
flowchart TD
Input[Receive Input] --> Validate{Validate Input}
Validate -->|Invalid| Reject["Reject with Error<br/>Return 400"]
Validate -->|Valid| Process[Process Request]
Process --> Output[Return Success]
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
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<br/>Log and Alert"]
subgraph ID["Name"]flowchart TD
User[User: Submit command] -->|1. Classify| Detector{Command Detector<br/>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
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
| 元素 | 语法 | 示例 |
|---|---|---|
| 节点(矩形) | ID[Label] | Node1[Process Data] |
| 节点(圆角) | ID(Label) | Start(Begin Process) |
| 节点(数据库) | ID[(Label)] | DB[(PostgreSQL)] |
| 节点(圆形) | ID((Label)) | Point((A)) |
| 决策 | ID{Label} | Check{Is Valid?} |
| 箭头 | --> | A --> B |
| 带标签的箭头 | -- text --> 或 `--> | text |
| 子图 | subgraph ID["Label"] | subgraph Sys["System"] |
| 样式 | style ID fill:#color | style Node1 fill:#e1f5ff |
| 注释 | %% comment | %% This is a note |
| 换行 | 在标签中使用 <br/> | Node["Line 1<br/>Line 2"] |
使用 mermaid-gen 技能时,主要输出是:
Mermaid 图表代码块:
mermaid 语言标识符的 Markdown 代码块示例输出:
```mermaid
flowchart TD
%% Define nodes
Start[Start Process] --> Process[Execute Task]
Process --> End[Complete]
%% Apply styling
style Start fill:#e1f5ff
style End fill:#c8e6c9
```
技能关系:
典型工作流程:
charts-flow 技能进行文件管理charts-flow 内部调用 mermaid-gen 来生成图表mermaid-gen 返回经过验证的 Mermaid 代码charts-flow 创建图表文件,生成 SVG,嵌入到父文档中独立使用:当用户只需要图表代码(不需要文件管理)时:
mermaid-gen组合使用:当用户需要完整的图表文件工作流程时:
charts-flow 技能(内部使用 mermaid-gen)mermaid-gen 的每个输出必须满足以下条件:
charts-flow 技能:
mermaid-gen 来生成图表内容diagrams/ 子目录中创建单独的图表文件doc-flow 技能:
mermaid-gen 创建的图表支持 ADR、SYS 文档和架构规范project-mngt 技能:
技术指南(根据 CLAUDE.md):
最佳实践集成:
mermaid-gen 确保语法正确性charts-flow 进行文件管理和性能优化每周安装次数
82
代码仓库
GitHub Stars
10
首次出现
Jan 24, 2026
安全审计
安装在
gemini-cli74
opencode74
codex72
cursor71
github-copilot70
cline69
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 :
Use mermaid-gen when :
Do NOT use mermaid-gen when :
charts-flow skill instead)Relationship to charts-flow skill :
charts-flow: Manages diagram files, generates SVG, embeds in documentsmermaid-gen: Ensures diagram syntax is correct before file creationcharts-flow skill calls mermaid-gen for diagram generation| 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" |
| 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 |
Follow this 5-step process to create or fix Mermaid diagrams:
<br/>) in double quotesNodeID[Display Label]%%) for complex sectionsError Recovery : If parse error occurs, see "Troubleshooting Guide" section below.
❌ 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:
<br/> tags❌ WRONG - Decimals and special chars without quotes:
Results[Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)]
✅ CORRECT - Wrap in double quotes when using with numbers/decimals:
Results["Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)"]
Rule: When node labels contain:
<br/> tags AND decimal numbers<br/> tags AND special charactersWrap the ENTIRE label in double quotes: NodeID["label content"]
❌ 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.
❌ 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:
subgraph ID["Display Name"]style ID fill:#color✅ CORRECT - Separate IDs from labels:
UserNode[User: Query the system] --> ProcessNode[Processing Service]
ProcessNode --> DBNode[(Database)]
Rule:
[) is the node ID (no spaces, use camelCase)[] is the display label (can have spaces, special chars when quoted)flowchart TD
%% Define nodes with clear IDs and labels
User[User Input] -->|Action| Service[Processing Service<br/>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
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
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
<br/> wrapped in double quotes|...|)%% comments<br/> tags instead)node1, node2 (use descriptive IDs)User Request :
"Create a flowchart showing the authentication flow: user submits credentials, system validates, checks database, returns token or error"
Skill Actions :
userInput, validator, dbCheck, tokenService, errorResponse, successResponseResult :
flowchart TD
userInput[User: Submit Credentials] -->|POST /auth| validator{Validate Format}
validator -->|Invalid| errorResponse["Error Response<br/>Status: 400"]
validator -->|Valid| dbCheck[(Database<br/>Verify User)]
dbCheck -->|Not Found| errorResponse
dbCheck -->|Found| tokenService[Generate JWT Token]
tokenService -->|Return| successResponse["Success Response<br/>Token + Expiry"]
User Request :
"My sequence diagram won't render. Error: 'Expecting SQE, got STR'. Here's the code:
User->>API: Request "data""
Skill Actions :
Request "data"Request dataResult :
sequenceDiagram
User->>API: Request data
API-->>User: Response
Explanation : Edge labels between |...| or after : should not contain quotes.
User Request :
"Create a state diagram for order processing: Draft → Submitted → Processing → Completed or Failed. Include transition conditions."
Skill Actions :
stateDiagram-v2 syntaxDraft, Submitted, Processing, Completed, FailedResult :
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
flowchart TD
Input[Receive Input] --> Validate{Validate Input}
Validate -->|Invalid| Reject["Reject with Error<br/>Return 400"]
Validate -->|Valid| Process[Process Request]
Process --> Output[Return Success]
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
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<br/>Log and Alert"]
subgraph ID["Name"]flowchart TD
User[User: Submit command] -->|1. Classify| Detector{Command Detector<br/>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
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
| 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)) |
When using the mermaid-gen skill, the primary output is:
Mermaid Diagram Code Block :
mermaid language identifierExample Output :
```mermaid
flowchart TD
%% Define nodes
Start[Start Process] --> Process[Execute Task]
Process --> End[Complete]
%% Apply styling
style Start fill:#e1f5ff
style End fill:#c8e6c9
```
Skill Relationship :
Typical Workflow :
charts-flow skill invoked for file managementcharts-flow internally calls mermaid-gen for diagram generationmermaid-gen returns validated Mermaid codecharts-flow creates diagram file, generates SVG, embeds in parent documentStandalone Usage : When user only needs diagram code (not file management):
mermaid-gen directlyCombined Usage : When user needs complete diagram file workflow:
charts-flow skill (which uses mermaid-gen internally)Every output from mermaid-gen must meet these criteria:
charts-flow Skill :
mermaid-gen to generate diagram contentdiagrams/ subdirectoriesdoc-flow Skill :
mermaid-gen support ADRs, SYS docs, and architecture specificationsproject-mngt Skill :
Technical Guidelines (per CLAUDE.md):
Best Practice Integration :
mermaid-gen for syntax correctnesscharts-flow for file management and performance optimizationWeekly Installs
82
Repository
GitHub Stars
10
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli74
opencode74
codex72
cursor71
github-copilot70
cline69
文档查找工具:实时获取库、框架和API最新文档,替代训练数据
1,100 周安装
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 | <br/> in label | Node["Line 1<br/>Line 2"] |