Agent skill

Utility Mermaid Diagrams

by product-on-purpose in product-on-purpose/pm-skills

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.

Apache-2.0Auto-check passedDevelopment

Install Utility Mermaid Diagrams

skills CLI
$ npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install product-on-purpose/pm-skills utility-mermaid-diagrams --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/product-on-purpose/pm-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/utility-mermaid-diagrams .claude/skills/utility-mermaid-diagrams && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
utility-mermaid-diagrams
GitHub stars
716
Token cost
~1.6k tokens
SKILL.md length
732 words
Files
8 (incl. references)
Skills in repo
68
Repo updated
First seen
Licence
Apache-2.0

At a glance

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.

  • Works in 6 steps: Quote labels - Any label containing… → Escape special characters - Characters… → Declare before referencing - Define a… → …
  • Tasks that involve Diagrams
  • SKILL.md covers When to Use, When NOT to Use, The Cardinal Rule and Diagram Selection Guide, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Utility Mermaid Diagrams is an agent skill from product-on-purpose/pm-skills. 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.

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 9 other files, including reference files (for example `HISTORY.md`, `evals/trigger-fixtures.json` and `references/EXAMPLE.md`).

It sits in Development, covering Diagrams. It works with Mermaid. The repository describes itself as: 68 plug-and-play, best-practice product management skills for AI agents: 30 Triple Diamond phase + 11 foundation + 12 utility + 15 tool (Foundation Sprint + Design Sprint). Plus… The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve Diagrams

Example prompts

  • “Use the utility-mermaid-diagrams skill to teach PMs to create syntactically valid mermaid diagrams by selecting the right diagram type for their…”
  • “/utility-mermaid-diagrams”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Quote labels - Any label containing spaces, parentheses, brackets, colons, commas, or reserved words must be quoted with double quotes
  2. Escape special characters - Characters with mermaid or markdown meaning (>, <, - at line start, #) need escaping or quoting
  3. Declare before referencing - Define a node before using it in an edge; referencing an undeclared node causes silent failures in some types
  4. Respect limits - Each diagram type has a maximum node/participant count beyond which readability collapses (see…
  5. Comment your intent - Use %% comments to document non-obvious choices (why this layout direction, why this grouping)
  6. Test before shipping - Paste into a mermaid renderer (mermaid.live, VS Code preview, or your target environment) and verify it renders…

What it can do on your machine

Read from SKILL.md and the folder at commit 1cef1a9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Utility Mermaid Diagrams loads about 1.6k tokens when it runs, and up to ~24k if it reads all its reference files. Until then it costs about 78 tokens; SKILL.md has 732 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~78
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~24k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from product-on-purpose/pm-skills at commit 1cef1a9, republished under its Apache-2.0 licence (© product-on-purpose). 732 words, ~1,623 tokens.

Download SKILL.mdSave it as .claude/skills/utility-mermaid-diagrams/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.
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
metadata.version
1.1.0
metadata.updated
2026-07-05
metadata.category
documentation
metadata.frameworks
mermaid
metadata.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...UseAlso consider
A decision or approval processFlowchartState
Multi-service or multi-party interactionsSequenceFlowchart
Feature lifecycle or status transitionsStateFlowchart
Work stages or pipeline statusKanbanState
Release or sprint timeline with dependenciesGanttTimeline
Version history or chronological milestonesTimelineGantt
2D prioritization (effort/impact, risk/value)Quadrant-
Allocation breakdown or compositionPieTreemap
Problem decomposition or brainstormingMindmap-
Domain models or data relationshipsERClass
API or object contractsClassER
System topology or infrastructureArchitectureFlowchart
Flow quantities or budget allocationSankeyPie
Hierarchical proportional dataTreemapPie
Trends or time-series metricsXY-Chart-

For worked examples organized by PM task, see references/pm-use-cases.md. For full syntax and options per type, see references/diagram-catalog.md.

Syntax Validity Principles

Six rules that prevent most rendering failures:

  1. Quote labels - Any label containing spaces, parentheses, brackets, colons, commas, or reserved words must be quoted with double quotes
  2. Escape special characters - Characters with mermaid or markdown meaning (>, <, - at line start, #) need escaping or quoting
  3. Declare before referencing - Define a node before using it in an edge; referencing an undeclared node causes silent failures in some types
  4. Respect limits - Each diagram type has a maximum node/participant count beyond which readability collapses (see references/diagram-catalog.md for per-type limits)
  5. Comment your intent - Use %% comments to document non-obvious choices (why this layout direction, why this grouping)
  6. Test before shipping - Paste into a mermaid renderer (mermaid.live, VS Code preview, or your target environment) and verify it renders correctly

For the complete syntax reference, see references/syntax-guide.md.

Show full SKILL.md (286 more words)Show less

Instructions

  1. Identify what you're communicating - What relationship, flow, hierarchy, or proportion needs to be visible? Who is the audience?
  2. Apply the cardinal rule - Confirm a diagram adds value over a list or table
  3. Select a diagram type - Use the selection guide above, browse references/pm-use-cases.md by task, or browse references/diagram-catalog.md by type
  4. Plan the diagram - Fill out the planning worksheet in references/TEMPLATE.md: purpose, audience, node inventory, type rationale
  5. Write the mermaid code - Follow references/syntax-guide.md rules; start with the minimal syntax example from references/diagram-catalog.md and expand
  6. Validate - Run through the quality checklist below
  7. Embed - Place the validated mermaid code block in your document

Output Contract

  • Planning artifact: A completed diagram planning worksheet (references/TEMPLATE.md)
  • Final output: A syntactically valid mermaid code block embedded in the target document
  • Quality gate: All items in the quality checklist pass

Quality Checklist

  • Diagram renders without error in target environment
  • Cardinal rule satisfied - a list or table would not communicate this more clearly
  • No linear sequences without branching, relationships, or hierarchy
  • All labels with spaces or special characters are properly quoted
  • Special characters escaped where needed
  • Node/participant count within type-specific limits
  • Colors are accessible (WCAG AA 3:1 contrast minimum, black text on light backgrounds)
  • Color is never the sole differentiator - shapes and labels also distinguish elements
  • Diagram has a descriptive title or surrounding prose context
  • %% comments document any non-obvious layout or grouping choices

References

FilePurpose
references/TEMPLATE.mdDiagram planning worksheet - fill out before writing mermaid code
references/EXAMPLE.mdWorked example: PM creating 4 diagrams for a product launch
references/diagram-catalog.mdAll 15 diagram types: syntax, PM examples, limits, pitfalls
references/pm-use-cases.mdPM task → diagram type mapping with mini worked examples
references/syntax-guide.mdComplete syntax validity rules, escaping, styling, and validation checklist

© product-on-purpose, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (references) in skills/utility-mermaid-diagrams of product-on-purpose/pm-skills.

  • SKILL.md
  • HISTORY.md
  • evals/trigger-fixtures.json
  • references/EXAMPLE.md
  • references/TEMPLATE.md
  • references/diagram-catalog.md
  • references/pm-use-cases.md
  • references/syntax-guide.md

Open the folder on GitHubat commit 1cef1a9

Compare with similar skills

Utility Mermaid Diagrams next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Utility Mermaid Diagrams compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Utility Mermaid Diagrams this skillproduct-on-purpose/pm-skills716—~1.6kAutomated safety check: PassApache-2.0
Archify Diagramstt-a1i/archify82k—~2.9kAutomated safety check: PassMIT
Diagram Designcathrynlavery/diagram-design49k1 repos~7.6kAutomated safety check: PassMIT
Draw.io Diagram StudioAgents365-ai/drawio-skill10k—~2.4kAutomated safety check: NotesMIT
Pretty Mermaid Rendererimxv/Pretty-mermaid-skills1.5k—~2kAutomated safety check: PassMIT
Archify Diagram BuilderUnclecheng-li/AI_Animation1.5k2 repos~4.1kAutomated safety check: PassMIT

Similar skills

  • Archify Diagrams

    tt-a1i/archify

    Creates interactive architecture, workflow, sequence, data-flow and lifecycle diagrams as standalone HTML with inline SVG, themes and image or video export.

    82k GitHub stars~2.9k tokensUpdated today
    DevelopmentAuto-check passed
  • Diagram Design

    cathrynlavery/diagram-design

    Creates branded diagrams, from architecture, flowchart and sequence to charts and maps, as self-contained HTML with inline SVG, with import from draw.io, Mermaid and Excalidraw.

    49k GitHub starsUsed in 1 repo~7.6k tokens
    DevelopmentAuto-check passed
  • Draw.io Diagram Studio

    Agents365-ai/drawio-skill

    Creates and edits editable draw.io diagrams from descriptions, code, infrastructure files, SQL and API schemas, with sync, review, test and export tools.

    10k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check: notes
  • Pretty Mermaid Renderer

    imxv/Pretty-mermaid-skills

    Writes and renders Mermaid diagrams as themed SVG, PNG or terminal ASCII and Unicode art with a bundled Node.js CLI that needs no browser.

    1.5k GitHub stars~2k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Archify Diagram Builder

    Unclecheng-li/AI_Animation

    Builds validated architecture, workflow, sequence, data-flow and lifecycle diagrams as standalone interactive HTML from a small JSON spec, with optional motion and image export.

    1.5k GitHub starsUsed in 2 repos~4.1k tokens
    DevelopmentAuto-check passed
  • Mermaid

    WH-2099/mermaid-skill

    Generate Mermaid diagrams from user requirements. An agent skill from WH-2099/mermaid-skill.

    288 GitHub starsUsed in 4 repos~958 tokens
    DevelopmentAuto-check passed

More from product-on-purpose/pm-skills

All 68 skills in this repo
  • Define Hypothesis

    product-on-purpose/pm-skills

    Defines a testable hypothesis with clear success metrics and a validation approach.

    716 GitHub stars~966 tokensUpdated 3 days ago
    Auto-check passed
  • Define Jtbd Canvas

    product-on-purpose/pm-skills

    Creates a Jobs to be Done canvas capturing the functional, emotional, and social dimensions of a customer job.

    716 GitHub stars~1.1k tokensUpdated 3 days ago
    Auto-check passed
  • Define Opportunity Tree

    product-on-purpose/pm-skills

    Creates an opportunity solution tree connecting a desired outcome to customer opportunities and candidate solutions, preventing solution-first jumps in continuous discovery.

    716 GitHub stars~1.1k tokensUpdated 3 days ago
    Auto-check passed
  • Define Problem Statement

    product-on-purpose/pm-skills

    Creates a clear problem framing document with user impact, business context, and success criteria.

    716 GitHub stars~932 tokensUpdated 3 days ago
    Auto-check passed
  • Deliver Acceptance Criteria

    product-on-purpose/pm-skills

    Generates structured Given/When/Then acceptance criteria for a user story or feature slice, covering the happy path, key failure scenarios, and non-functional expectations in testable form.

    716 GitHub stars~1k tokensUpdated 3 days ago
    Auto-check passed
  • Deliver Launch Checklist

    product-on-purpose/pm-skills

    Creates a cross-functional pre-launch checklist covering engineering, design, marketing, support, legal, and operations readiness, with owners, dates, and go/no-go criteria so nothing is missed…

    716 GitHub stars~970 tokensUpdated 3 days ago
    Auto-check passed

Works with

Categories

Questions about Utility Mermaid Diagrams

What does Utility Mermaid Diagrams do?

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. Utility Mermaid Diagrams is an agent skill from product-on-purpose/pm-skills. 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.

When should I use Utility Mermaid Diagrams?

Utility Mermaid Diagrams fits situations like: tasks that involve Diagrams.

How do I install Utility Mermaid Diagrams in Claude Code?

Run `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a claude-code`. Or copy the skill folder (skills/utility-mermaid-diagrams in product-on-purpose/pm-skills) into .claude/skills/utility-mermaid-diagrams in your project. Claude Code loads it when a task matches its description.

How do I install Utility Mermaid Diagrams in Codex?

Run `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a codex`. Or copy the skill folder (skills/utility-mermaid-diagrams in product-on-purpose/pm-skills) into .agents/skills/utility-mermaid-diagrams in your project. Codex loads it when a task matches its description.

Can I use Utility Mermaid Diagrams in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add product-on-purpose/pm-skills --skill utility-mermaid-diagrams -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/utility-mermaid-diagrams, .gemini/skills/utility-mermaid-diagrams, .github/skills/utility-mermaid-diagrams and .opencode/skills/utility-mermaid-diagrams in your project.

What does Utility Mermaid Diagrams need to run?

SKILL.md names no scripts, command-line tools or credentials: Utility Mermaid Diagrams is instructions for the agent only.

Does Utility Mermaid Diagrams access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Utility Mermaid Diagrams safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Utility Mermaid Diagrams use?

Utility Mermaid Diagrams is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Utility Mermaid Diagrams use?

About 1.6k tokens (SKILL.md is roughly 6.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 23k tokens, read only when the agent opens those files.

What are the alternatives to Utility Mermaid Diagrams?

Skills that share tags, products or a category with Utility Mermaid Diagrams: Archify Diagrams (tt-a1i/archify, 82k stars), Diagram Design (cathrynlavery/diagram-design, 49k stars), Draw.io Diagram Studio (Agents365-ai/drawio-skill, 10k stars) and Pretty Mermaid Renderer (imxv/Pretty-mermaid-skills, 1.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Utility Mermaid Diagrams?

product-on-purpose (a GitHub organization) maintains it in product-on-purpose/pm-skills, which has 716 GitHub stars. The repository holds 68 skills in this directory. The repository was last updated on October 8, 2026.

Source: product-on-purpose/pm-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.