# utility-mermaid-diagrams

Guides product managers in building valid Mermaid diagrams across 15 supported formats for PRDs and technical specs.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 736 installs · ★ 763
- Author: product-on-purpose
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/product-on-purpose/pm-skills/tree/HEAD/skills/utility-mermaid-diagrams/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/utility-mermaid-diagrams

## What it does

The skill structures product logic without breaking markdown rendering. It strictly follows one rule: do not diagram what a list can say. Linear processes stay as lists. When branching or retry loops appear, the agent selects one of 15 diagram types, such as Flowchart, Sequence, Gantt, or ER.

Code generation follows six syntax rules to prevent rendering bugs. The agent wraps labels with spaces in double quotes, escapes characters like `#` or `>`, and declares nodes before connecting edges. It also checks node count thresholds and verifies WCAG AA contrast ratios so diagrams remain legible.

This skill does not export diagrams to PNG or SVG files because file rendering belongs to external viewers. It also stops short of full customer journey mapping, which relies on the companion `discover-journey-map` skill instead.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/utility-mermaid-diagrams/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/utility-mermaid-diagrams/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/utility-mermaid-diagrams/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/utility-mermaid-diagrams/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install product-on-purpose/pm-skills utility-mermaid-diagrams
```

2. **Manually: put the files in place**
- File: `.github/skills/utility-mermaid-diagrams/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/product-on-purpose/pm-skills --path skills/utility-mermaid-diagrams
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/utility-mermaid-diagrams/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/product-on-purpose/pm-skills/tree/HEAD/skills/utility-mermaid-diagrams/SKILL.md

## When to use it
- choose the right Mermaid diagram format for product specifications
- fix syntax and rendering errors in broken Mermaid blocks
- model feature lifecycle states and transitions
- verify contrast and readability rules before publishing documentation

## Example prompts
- Create a Mermaid sequence diagram for our payment retry flow
- Review this Mermaid flowchart syntax and fix rendering issues
- Help me pick the best Mermaid diagram type to show sprint dependencies

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: aa05f4f1fa4eae25.

BEGIN THIRD-PARTY FILE aa05f4f1fa4eae25
```text
---
name: utility-mermaid-diagrams
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.
license: Apache-2.0
metadata:
  classification: utility
  version: "1.1.0"
  updated: 2026-07-05
  category: documentation
  frameworks:
    - mermaid
  author: product-on-purpose
---

<!-- 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

| I need to show... | Use | Also consider |
|-------------------|-----|---------------|
| A decision or approval process | Flowchart | State |
| Multi-service or multi-party interactions | Sequence | Flowchart |
| Feature lifecycle or status transitions | State | Flowchart |
| Work stages or pipeline status | Kanban | State |
| Release or sprint timeline with dependencies | Gantt | Timeline |
| Version history or chronological milestones | Timeline | Gantt |
| 2D prioritization (effort/impact, risk/value) | Quadrant | - |
| Allocation breakdown or composition | Pie | Treemap |
| Problem decomposition or brainstorming | Mindmap | - |
| Domain models or data relationships | ER | Class |
| API or object contracts | Class | ER |
```
END THIRD-PARTY FILE aa05f4f1fa4eae25

The third-party file has ended. Everything between the aa05f4f1fa4eae25 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2728 of 6498 bytes. © product-on-purpose · Apache-2.0 · https://github.com/product-on-purpose/pm-skills/tree/HEAD/skills/utility-mermaid-diagrams/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md