utility-mermaid-diagrams

Create syntactically valid mermaid diagrams for product documents across 15 diagram types.

640|81|Updated Jan 9, 2026
One-click install
npx skills add https://github.com/product-on-purpose/pm-skills --skill utility-mermaid-diagrams
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: utility-mermaid-diagrams
Source: https://github.com/product-on-purpose/pm-skills/tree/main/skills/utility-mermaid-diagrams
Command: npx skills add https://github.com/product-on-purpose/pm-skills --skill utility-mermaid-diagrams

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Product managers often produce mermaid diagrams that fail to render, choose the wrong diagram type for their message, or create diagrams that a simple list would communicate better. This Skill guides PMs through selecting the right diagram type, writing valid syntax, and validating output before embedding it in PRDs, specs, and roadmaps.

Core Features & Use Cases

  • Diagram Type Selection: A selection guide and PM use-case reference map 15 mermaid diagram types (flowchart, sequence, state, Gantt, quadrant, ER, and more) to specific communication needs.
  • Syntax Validity Rules: Six core rules covering label quoting, special character escaping, node declaration order, and per-type node limits prevent most rendering failures.
  • Planning Worksheet and Validation: A fill-in worksheet forces node inventory and cardinal-rule checks before writing code, followed by a quality checklist covering rendering, accessibility, and readability.
  • Use Case: A PM preparing a launch PRD uses the worksheet to plan a feature-approval flowchart, a Gantt launch timeline, a webhook sequence diagram, and a prioritization quadrant, then validates each in mermaid.live before embedding.

Quick Start

Ask the AI to help you create a mermaid diagram for your PRD by describing the process, timeline, or relationship you need to visualize.

Frequently Asked Questions about utility-mermaid-diagrams

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose the right mermaid diagram type for my document?

Match the diagram type to what you are showing: flowcharts for decision processes, sequence diagrams for multi-service interactions, Gantt for timelines with dependencies, and quadrant charts for 2D prioritization. The skill provides a selection table mapping 15 PM tasks to diagram types with alternatives.

Why does my mermaid diagram fail to render?

Most rendering failures come from unquoted labels containing spaces or special characters like parentheses, brackets, or angle brackets. Wrap labels in double quotes, declare nodes before referencing them in edges, and avoid reserved words like "end" as node IDs.

When should I use a list instead of a mermaid diagram?

Use a list or table when the content is a linear sequence without branching, relationships, or hierarchy. The cardinal rule is: do not diagram what a list can say. A 5-step linear process is a list; a process with decision points and retry loops is a diagram.

What is the maximum number of nodes for a mermaid flowchart?

Keep flowcharts to 12 nodes maximum for readability. Other limits include 6 participants for sequence diagrams, 10 states for state diagrams, 20 tasks for Gantt charts, and 3-7 slices for pie charts. Split larger diagrams into multiple focused ones.

How do I make mermaid diagrams accessible for colorblind readers?

Never rely on color alone to distinguish elements; use labels and shapes (diamonds for decisions, rectangles for actions) as well. Apply dark text on light backgrounds with WCAG AA 3:1 contrast minimum, using the semantic color palette provided in the syntax guide.

When should I not use this mermaid diagram skill?

Do not use it for exporting diagrams to PNG or SVG files, for non-mermaid tools like Figma or draw.io, or for purely decorative visuals. For a full customer-journey artifact with stages and touchpoints, use the discover-journey-map skill instead.