Agent-Skills.md

Agent Skills: Mermaid Diagrams

Expert knowledge for creating print-ready Mermaid diagrams -- syntax, styling, theming, and print optimization. Use when generating or reviewing any Mermaid diagram.

UncategorizedID: nathanvale/side-quest-marketplace/mermaid-diagrams

Repository

nathanvale/side-quest-marketplace
nathanvaleLicense: MIT
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/nathanvale/side-quest-marketplace/tree/HEAD/plugins/cortex-engineering/skills/mermaid-diagrams

Skill Files

Browse the full folder contents for mermaid-diagrams.

Download Skill

Loading file tree…

plugins/cortex-engineering/skills/mermaid-diagrams/SKILL.md

Skill Metadata

Name
mermaid-diagrams
Description
Expert knowledge for creating print-ready Mermaid diagrams -- syntax, styling, theming, and print optimization. Use when generating or reviewing any Mermaid diagram.

Mermaid Diagrams

Background knowledge for producing clean, readable, print-ready Mermaid diagrams. This skill provides the craft -- the visualize skill provides the workflow.

Scope: Mermaid is the engine for all non-mind-map diagram types. Mind maps auto-route to Markmap via the visualize skill. Users can override to Mermaid for mind maps if they prefer themed presets over Markmap's visual quality.

Curated visual identity: All diagrams use one of three preset configs. Each preset pairs a theme, look mode, and layout engine. See default-theme.md for the full specification.

Quick Start

Minimal correct diagram (Classic preset, the default):

flowchart LR
    classDef primary fill:#0072B2,color:#fff,stroke:#005a8c,stroke-width:2px
    classDef success fill:#009E73,color:#fff,stroke:#006B4F,stroke-width:2px
    classDef warning fill:#E69F00,color:#000,stroke:#B37A00,stroke-width:2px

    A[Input]:::primary --> B{Valid?}:::warning
    B -->|Yes| C[Process]:::primary
    B -->|No| D[Error]:::warning
    C --> E[Done]:::success

Export with Classic preset (default):

bunx @mermaid-js/mermaid-cli -i input.mmd -o output.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white

Core Principles

Non-negotiable rules for every diagram:

  1. Max 15 nodes per diagram. Split into multiple diagrams if larger.
  2. Max 3 shapes per diagram. More shapes become visual noise.
  3. Use classDef, not inline styles. Keeps diagrams consistent and maintainable.
  4. Use a preset config via -c flag for all visualize-skill output. Never put %%{init:}%% directives in generated diagrams -- the config file handles theming. Three presets: default-theme.json (Classic), sketch-theme.json (Sketch), blueprint-theme.json (Blueprint).

Diagram Type Selection

Pick the right diagram for the job. Default to the simplest type that communicates the idea.

| Diagram | Keyword | Best for | |---------|---------|----------| | Flowchart | flowchart TD | Processes, workflows, decision trees | | Sequence | sequenceDiagram | Interactions between components/actors over time | | Mind map | mindmap | Brainstorms, topic exploration, hierarchical ideas | | Class | classDiagram | Object models, type hierarchies, interfaces | | State | stateDiagram-v2 | Lifecycles, state machines, status transitions | | ER | erDiagram | Data models, database schemas, entity relationships | | Gantt | gantt | Timelines, project schedules, phased plans | | Pie | pie | Proportions, distributions, simple breakdowns | | Timeline | timeline | Chronological events, history, roadmaps | | Architecture | architecture-beta | System components and their connections | | Block | block-beta | Generic block diagrams, layout-driven visuals | | Quadrant | quadrantChart | 2x2 matrices, priority/effort grids | | Sankey | sankey-beta | Flow volumes, resource distribution | | XY chart | xychart-beta | Line/bar charts with axes | | Treemap | treemap-beta | Hierarchical data as nested rectangles | | Kanban | kanban | Board-style task tracking | | Packet | packet-beta | Network packet structures | | Requirement | requirementDiagram | Requirements traceability | | Radar | radar-beta | Multi-axis comparison (v11.6.0+) | | Git graph | gitGraph | Branch/commit visualization | | C4 Context | C4Context | System context (C4 model) |

Decision heuristic: If you're unsure, start with flowchart TD. It handles 70% of use cases. Upgrade to a specialized type only when the data demands it.

Core Styling Principles

1. Readability first

  • Max 15 nodes per diagram. Split into multiple diagrams if larger.
  • Max 3-5 main branches for mind maps.
  • Keep node labels under 30 characters. Use abbreviations + a legend if needed.
  • Prefer <br/> over backtick markdown-string syntax for line breaks -- backtick labels cause dagre layout cramping with 10+ nodes.
  • Max 2 lines per node label. Move detail to edge labels, legends, or index.md.
  • One concept per node. Never combine two ideas.

2. Direction matters

| Direction | Code | When to use | |-----------|------|-------------| | Top-down | TD or TB | Hierarchies, org charts, inheritance | | Left-right | LR | Pipelines, sequences, timelines | | Right-left | RL | Reverse flows, rollback processes | | Bottom-up | BT | Dependency trees (leaf to root) |

3. Grouping with subgraphs

Use subgraph to visually cluster related nodes. Label every subgraph. Keep nesting to 2 levels max -- deeper nesting kills readability at print scale.

subgraph "API Layer"
    A[REST Controller] --> B[Service]
    B --> C[Repository]
end

4. Edge labels

Label every edge that isn't self-explanatory. Use -->|label| syntax. Keep labels to 1-3 words.

Theme Configuration

Init directive

Place at the top of any diagram to configure theme and variables:

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A --> B

Built-in themes

| Theme | Use for | |-------|---------| | base | Default choice. Blank slate with custom themeVariables. Used by default-theme.json. | | neutral | Black on white, high contrast, no colored fills. Good for B&W printing. | | default | Screen viewing. Mermaid's standard blue palette | | dark | Dark backgrounds. Inverted colors | | forest | Green palette. Good for environmental/organic topics |

Use base with default-theme.json for all visualize skill output. The neutral theme silently ignores themeVariables (GitHub #4264), so base is the only option for custom palettes.

Custom theme variables

Override specific colors via themeVariables in the init directive:

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a90d9',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#2c5f8a',
    'lineColor': '#333333',
    'secondaryColor': '#f0f4f8',
    'tertiaryColor': '#e8e8e8',
    'fontSize': '16px'
}}}%%

Important: Mermaid only recognizes hex colors (#4a90d9), not color names (blue).

Node Shapes

Flowcharts support many shapes. Use them semantically:

| Shape | Syntax | Semantic meaning | |-------|--------|-----------------| | Rectangle | [text] | Process, action, step | | Rounded | (text) | Start/end, terminal | | Stadium | ([text]) | Start/end (alternative) | | Diamond | {text} | Decision, condition | | Hexagon | {{text}} | Preparation, setup | | Circle | ((text)) | Connector, junction | | Cylinder | [(text)] | Database, data store | | Parallelogram | [/text/] | Input/output | | Subroutine | [[text]] | Predefined process, function call | | Trapezoid | [/text\] | Manual operation | | Double circle | (((text))) | Double-click event, emphasis |

Rule of thumb: Use max 3 different shapes per diagram. More than that and the visual language becomes noise.

Print-Safe Color Palette

When color is needed on print diagrams, use this accessible palette. Based on the Wong palette (Nature Methods, 2011) -- the standard for colorblind-safe scientific visualization. All colors maintain WCAG AA contrast against white.

| Role | Hex | classDef name | Usage | |------|-----|--------------|-------| | Primary | #0072B2 | primary | Main nodes, primary flow | | Info | #56B4E9 | info | Information, notes | | Success | #009E73 | success | Success states, completed | | Warning | #E69F00 | warning | Warnings, decision points (dark text) | | Danger | #D55E00 | danger | Error states, failures | | Highlight | #F0E442 | highlight | Emphasis, callouts | | Accent | #CC79A7 | accent | Tertiary accent |

The full classDef block is in default-theme.md. Apply with ::::

classDef primary fill:#0072B2,color:#fff,stroke:#005a8c
classDef secondary fill:#009E73,color:#fff,stroke:#007a5a
classDef accent fill:#E69F00,color:#000,stroke:#b87d00

A[Start]:::primary --> B{Check}:::accent
B -->|Pass| C[Done]:::secondary

Font Sizing for Print

These minimums ensure readability at 1-2 meters viewing distance on A3/A2 paper:

| Element | Minimum | |---------|---------| | Node labels | 14pt | | Edge labels | 12pt | | Subgraph titles | 16pt | | Root/title nodes | 18pt |

Set via init directive:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '16px'}}}%%

Export with mmdc CLI

The @mermaid-js/mermaid-cli (mmdc) is the primary export path. Use with -c <preset>-theme.json for the curated visual identity. The MCP server's export_diagram_formats produces placeholder files -- do not use it for export.

Basic export

bunx @mermaid-js/mermaid-cli -i input.mmd -o output.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white

Key flags

| Flag | Purpose | Default | |------|---------|---------| | -i | Input file | (required) | | -o | Output file (.svg, .pdf, .png) | (required) | | -t | Theme | default | | -b | Background color | white | | -w | Width in pixels | 800 | | -H | Height in pixels | auto | | --scale | Scale factor | 1 | | -c | Config JSON file | none |

Print-ready export

# A4 landscape SVG (default)
bunx @mermaid-js/mermaid-cli -i input.mmd -o diagram.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white -w 3508 -H 2480

# A3 landscape SVG (wall poster)
bunx @mermaid-js/mermaid-cli -i input.mmd -o diagram.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white -w 4961 -H 3508

# PDF for direct printing (add --pdfFit)
bunx @mermaid-js/mermaid-cli -i input.mmd -o diagram.pdf \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white -w 3508 -H 2480 --pdfFit

A4 landscape = 3508 x 2480px at 300 DPI. A3 landscape = 4961 x 3508px.

Quality Checklist

Verify before finalizing any diagram:

  • [ ] Max 15 nodes
  • [ ] Labels under 30 characters
  • [ ] Node labels max 2 lines, using <br/> (not backtick syntax)
  • [ ] Max 3 different shapes
  • [ ] All non-obvious edges labeled
  • [ ] Subgraph nesting max 2 levels
  • [ ] Font size >= 14pt for nodes
  • [ ] Color + shape together (not color alone)
  • [ ] No %%{init:}%% in visualize-skill output

Anti-Patterns

| Don't | Do instead | |-------|------------| | 20+ nodes in one diagram | Split into 2-3 focused diagrams | | Crossing edges everywhere | Restructure node order to minimize crossings | | Rainbow colors | Max 3-4 colors with semantic meaning | | Tiny text with fontSize: '10px' | Minimum 14pt for nodes, 12pt for edges | | Unlabeled edges | Label every non-obvious connection | | Deep subgraph nesting (3+) | Flatten to max 2 levels | | Color as only differentiator | Combine color with shape or label prefix | | default theme for print | Use neutral -- saves ink, better contrast | | Inline styles on every node | Use classDef for consistent, reusable styles | | Giant node labels | 30 chars max, use abbreviations + legend | | Backtick markdown-string labels | <br/> for line breaks (dagre calculates width correctly) |

Done When

The diagram is complete when every item in the Quality Checklist above passes and the exported file (SVG/PDF/PNG) renders correctly at the target paper size.

Reference Files

For comprehensive details, see: