# Utility Mermaid Diagrams

Teaches PMs to create syntactically valid mermaid diagrams by selecting the right...

- Repository: https://github.com/product-on-purpose/pm-skills (780 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -g -a claude-code -y`
Codex: `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -g -a codex -y`
Cursor: `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -g -a cursor -y`
Gemini CLI: `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add product-on-purpose/pm-skills`

## Description

Teaches PMs to create syntactically valid mermaid diagrams by selecting the right diagram type for their communication need, following syntax validity rules, and validating before shipping. Covers all 15 mermaid diagram types with PM-relevant examples and a dual-lens navigation system.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->

# Mermaid Diagrams

Create effective, syntactically valid mermaid diagrams for product documents.

## When to Use

- Creating mermaid diagrams for PRDs, specs, roadmaps, or stakeholder presentations
- Choosing which of 15 diagram types fits a specific communication need
- Debugging mermaid code that won't render or renders incorrectly
- Reviewing diagrams for clarity, accuracy, and accessibility

## When NOT to Use

- Exporting diagrams to image files (PNG/SVG) - that's a rendering tool concern
- Using non-mermaid diagramming tools (Figma, Lucidchart, draw.io)
- Creating purely decorative visuals with no informational purpose
- Producing a full customer-journey artifact (stages, touchpoints, emotional curve, pain points) rather than a standalone diagram - use `discover-journey-map`, which composes this skill for its timeline or flowchart section

## The Cardinal Rule

> Don't diagram what a list can say.

Diagrams earn their place when they reveal **relationships**, **branching**, or **flow** that prose flattens. Before creating any diagram, ask:

*Does this show branching, relationships, or flow that a list or table would flatten?*

- **Yes** → proceed with a diagram
- **No** → use a numbered list, bullet list, or table instead

A 5-step linear process is a list. A 5-step process with two decision points and a retry loop is a diagram.

## Diagram Selection Guide

The rest: https://github.com/product-on-purpose/pm-skills/blob/HEAD/skills/utility-mermaid-diagrams/SKILL.md