CRITICAL: Mermaid is a Markdown-focused diagramming tool. This skill should be triggered when the user explicitly mentions "Mermaid", needs diagrams for Markdown documentation, or wants diagrams that render directly in Markdown renderers (GitHub, GitLab, wikis, blogs).
Trigger this skill when you see:
- User says "用 Mermaid" (use Mermaid), "Mermaid 画图" (draw with Mermaid), "Markdown 图" (Markdown diagram)
- User needs diagrams for Markdown documentation, GitHub, GitLab, wikis, or blogs
- User wants quick diagrams that render directly in Markdown renderers
- User mentions any diagram type for Markdown: flowchart, sequence diagram, class diagram, etc.
- User wants to visualize, represent, or illustrate something with a diagram in Markdown format
When both PlantUML and Mermaid are matched, ALWAYS ask the user to choose the output format or tool, as they are two different diagramming tools with different purposes.
To create a Mermaid diagram:
- Identify the diagram type from the user's request:
- Flowchart/flow chart/流程图 → flowchart or graph
- Sequence diagram/时序图 → sequenceDiagram
- Class diagram/类图 → classDiagram
- State diagram/状态图 → stateDiagram or stateDiagram-v2
- Entity relationship diagram/实体关系图 → erDiagram
- User journey/用户旅程图 → journey
- Gantt chart/甘特图 → gantt
- Pie chart/饼图 → pie
- Quadrant chart/象限图 → quadrantChart
- Requirement diagram/需求图 → requirementDiagram
- Git graph/Git图 → gitGraph
- C4 diagram/C4图 → C4Context, C4Container, C4Component, C4Deployment, or C4Dynamic
- Mindmap/思维导图 → mindmap
- Timeline/时间线图 → timeline
- ZenUML/禅UML → zenuml
- Sankey diagram/桑基图 → sankey
- XY chart/XY图 → xychart
- Block diagram/方块图 → block
- Packet diagram/数据包图 → packet
- Kanban/看板图 → kanban
- Architecture diagram/架构图 → architecture-beta (requires Mermaid v11.1.0+)
- Radar chart/雷达图 → radar-beta (requires Mermaid v11.1.0+)
- Treemap/树状图 → treemap-beta (requires Mermaid v11.1.0+)
- Load the appropriate example file from the
examples/ directory:
- examples/flowchart.md - For flowcharts and process diagrams
- examples/sequence.md - For sequence diagrams showing interactions
- examples/class.md - For class diagrams and object-oriented designs
- examples/state.md - For state diagrams and state machines
- examples/er.md - For entity relationship diagrams
- examples/journey.md - For user journey maps
- examples/gantt.md - For Gantt charts and project timelines
- examples/pie.md - For pie charts
- examples/quadrant.md - For quadrant charts
- examples/requirement.md - For requirement diagrams
- examples/gitgraph.md - For Git branching diagrams
- examples/c4.md - For C4 architecture diagrams
- examples/mindmap.md - For mindmaps
- examples/timeline.md - For timeline diagrams
- examples/zenuml.md - For ZenUML diagrams
- examples/sankey.md - For Sankey flow diagrams
- examples/xychart.md - For XY charts (bar/line charts)
- examples/block.md - For block diagrams
- examples/packet.md - For packet diagrams
- examples/kanban.md - For Kanban boards
- examples/architecture.md - For architecture diagrams
- examples/radar.md - For radar charts
- examples/treemap.md - For treemap diagrams
- Follow the specific instructions in that example file for syntax, structure, and best practices
Important Notes:
- Beta diagram types (architecture-beta, radar-beta, treemap-beta) require Mermaid v11.1.0 or higher
- If the rendering environment doesn't support beta diagram types, use the flowchart alternatives provided in the example files
- Always check the example file for version compatibility notes and alternative syntax options
- Generate the Mermaid code wrapped in a Markdown code block with proper syntax highlighting:
IMPORTANT: Always wrap the Mermaid code in a Markdown code block with mermaid language tag. This ensures the format is preserved when users copy the content.
Example format (use actual Mermaid syntax, not placeholders):
```mermaid
flowchart TD
A[Start] --> B[Process]
B --> C[End]
```
Output Format Requirements:
- Always use triple backticks (``) with mermaid` language tag
- Never output raw Mermaid code without code block markers
- The code block must be complete and properly formatted
- Use actual valid Mermaid syntax, not placeholders like ...diagram content...
- This ensures users can copy the code without losing formatting
- Include styling and configuration when needed:
- Use %%{ init: { theme: 'base' } }%% for theme configuration
- Apply style directives for node styling
- Use classDef for reusable style classes
- Validate the syntax:
- Ensure all required elements are present
- Check that relationships and connections are properly defined
- Verify date formats for Gantt charts (YYYY-MM-DD)
- Confirm data formats for charts (pie, quadrant, etc.)
- For ER diagrams: Use underscores instead of hyphens in entity names (e.g., LINE_ITEM not LINE-ITEM)
- For flowcharts: Avoid using "end" as a node label (use "End" or "END" instead)
- For class diagrams: Escape special characters in labels using backticks
- Check version compatibility for beta diagram types
- Save the diagram to project directory:
- Default behavior: When generating a Mermaid diagram, save it to the current project directory
- Recommended locations:
- docs/diagrams/ - For documentation diagrams
- docs/ - For general documentation
- diagrams/ - For standalone diagram files
- Current directory (.) - If no specific directory structure exists
- File naming: Use descriptive names like system-architecture.md, user-flow.md, database-schema.md, etc.
- File format: Save as .md file with the Mermaid code block inside
- Example: If user requests a system architecture diagram, save it as docs/diagrams/system-architecture.md or diagrams/system-architecture.md
- Ask if needed: If the project structure is unclear, ask the user where they'd like the diagram saved, but default to creating a docs/ or diagrams/ directory if it doesn't exist
Output Format and File Saving:
When generating a diagram, follow this response structure:
- Save the file first: Create the diagram file in the project directory (e.g.,
docs/diagrams/system-architecture.md)
- Inform the user: Tell them where the file was saved
- Display the diagram: Show the Mermaid code in a properly formatted Markdown code block with
mermaid language tag
Example Response Structure:
- First line: "I've created the Mermaid diagram and saved it to
docs/diagrams/system-architecture.md." - Then show the diagram wrapped in a code block:
- Start with: three backticks + mermaid + newline
- Then the Mermaid code
- End with: three backticks + newline
Critical Requirements:
- The Mermaid code block MUST ALWAYS be properly formatted with triple backticks (``
) and mermaid` language tag - NEVER output raw Mermaid code without code block markers
- The code block must be complete (opening and closing backticks)
- This ensures users can copy the code without losing formatting
- Always save the diagram file to the current project directory (default:
docs/diagrams/ or diagrams/)
If the diagram type doesn't match any existing example, refer to the Mermaid documentation or ask the user for clarification about the desired visualization.
|