markdown-mermaid-writing – Documents & Office skill for AI agents

Markdown and Mermaid Writing

Overview

This skill provides an optional house style for **Markdown documentation with Mermaid

structural diagrams**. Follow the requested output format, existing repository conventions,

and journal requirements first. This skill does not replace scientific analysis or plotting.

A relationship expressed as Mermaid inside a .md file is editable text that diffs

cleanly in git. A compatible host renders it without a separate user build step.

It renders where the host has Mermaid support; plain Markdown viewers may show only code,

and platforms/extensions ship different Mermaid versions. It uses

a compact source representation, though token use depends on the diagram. Exporting

SVG/PNG requires a renderer; retain the diagram source alongside exported figures.

> "The more you get your reports and files in .md in just regular text, which mermaid is

> as well as being a simple 'script language'. This just helps with any downstream rendering

> and especially AI generated images (using mermaid instead of just long form text to

> describe relationships < tokens). Additionally mermaid can render along with markdown for

> easy use almost anywhere by humans or AI."

>

> — Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

When to Use This Skill

Use this skill when:

• Writing a requested Markdown report, README, methods overview, or research note
• Diagramming a workflow, data pipeline, schema, state machine, or conceptual relationship
• Maintaining editable Mermaid sources and their rendered SVG/PNG exports

Use scientific plotting tools directly for measured data, uncertainty, statistical graphics,

exact geometry, or publication figures that Mermaid cannot faithfully represent. Mermaid

is not a required precursor to a quantitative chart or an existing SVG/code-native asset.

🎨 The Source Format Philosophy

Why text-based diagrams win

| What matters | Mermaid in Markdown | Python / AI Image |

| ----------------------------- | :-----------------: | :---------------: |

| Git diff readable | ✅ text source | Plotting code/SVG can also be text |

| Editable source | ✅ | Plotting scripts and vector sources are editable |

| Compact relationship notation | Often | Depends on representation |

| Native preview | Host/version dependent | Viewer/format dependent |

| Parseable by AI without vision | ✅ | ❌ |

| Works in destination | Check Mermaid support and version | Check image format support |

| Accessible (screen readers) | Check SVG metadata and text alternative | Provide alt text/data table |

| Convertible to image later | ✅ anytime | — already image |

The three-phase workflow

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Markdown holds the structural diagram source. Quantitative charts come from data and plotting code; optional illustrations require a separate factual review.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(structural source)"]
    p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
    p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
    out["📊 Final Deliverable"]

    p1 --> out
    data["Data and plotting code"] --> p2
    p1 -.->|"when needed"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

Retain Mermaid for structural diagrams and data/code for quantitative charts. An AI illustration

is not a quantitative conversion; verify every label and relationship against its sources.

What Mermaid can express

This skill includes 23 diagram-type guides plus a composition guide. Mermaid supports

additional types; these references are a curated subset, not an exhaustive version catalogue:

| Use case | Diagram type | File |

| -------------------------------------------- | ---------------- | ---------------------------------------------------- |

| Experimental workflow / decision logic | Flowchart | references/diagrams/flowchart.md |

| Service interactions / API calls / messaging | Sequence | references/diagrams/sequence.md |

| Data model / schema | ER diagram | references/diagrams/er.md |

| State machine / lifecycle | State | references/diagrams/state.md |

| Project timeline / roadmap | Gantt | references/diagrams/gantt.md |

| Proportions / composition | Pie | references/diagrams/pie.md |

| System architecture (zoom levels) | C4 | references/diagrams/c4.md |

| Concept hierarchy / brainstorm | Mindmap | references/diagrams/mindmap.md |

| Chronological events / history | Timeline | references/diagrams/timeline.md |

| Class hierarchy / type relationships | Class | references/diagrams/class.md |

| User journey / satisfaction map | User Journey | references/diagrams/user_journey.md |

| Two-axis comparison / prioritization | Quadrant | references/diagrams/quadrant.md |

| Requirements traceability | Requirement | references/diagrams/requirement.md |

| Flow magnitude / resource distribution | Sankey | references/diagrams/sankey.md |

| Numeric trends / bar + line charts | XY Chart | references/diagrams/xy_chart.md |

| Component layout / spatial arrangement | Block | references/diagrams/block.md |

| Work item status / task columns | Kanban | references/diagrams/kanban.md |

| Cloud infrastructure / service topology | Architecture | references/diagrams/architecture.md |

| Multi-dimensional comparison / skills radar | Radar | references/diagrams/radar.md |

| Hierarchical proportions / budget | Treemap | references/diagrams/treemap.md |

| Binary protocol / data format | Packet | references/diagrams/packet.md |

| Git branching / merge strategy | Git Graph | references/diagrams/git_graph.md |

| Code-style sequence (programming syntax) | ZenUML | references/diagrams/zenuml.md |

| Multi-diagram composition patterns | Complex Examples | references/diagrams/complex_examples.md |

> 💡 Pick the right type, not the easy one. Don't default to flowcharts for everything.

> A timeline beats a flowchart for chronological events. A sequence beats a flowchart for

> service interactions. Scan the table and match.

---

🔧 Core workflow

Step 1: Identify the document type

Check if a template exists before writing from scratch:

| Document type | Template |

| ------------------------------ | ----------------------------------------------- |

| Pull request record | templates/pull_request.md |

| Issue / bug / feature request | templates/issue.md |

| Sprint / project board | templates/kanban.md |

| Architecture decision (ADR) | templates/decision_record.md |

| Presentation / briefing | templates/presentation.md |

| Research paper / analysis | templates/research_paper.md |

| Project documentation | templates/project_documentation.md |

| How-to / tutorial | templates/how_to_guide.md |

| Status report | templates/status_report.md |

Step 2: Read the style guide

For this Markdown workflow, read references/markdown_style_guide.md. Treat emoji,

heading counts, and horizontal rules as house style rather than Markdown syntax requirements.

Key rules to internalize:

• One H1 per document — the title. Never more.
• Emoji on H2 headings only — one emoji per H2, none in H3/H4
• Support factual claims — use verified sources and the requested citation format
• Bold sparingly — max 2-3 bold terms per paragraph, never full sentences
• Optional horizontal rules after </details> when they improve separation
• Tables over prose for comparisons, configurations, structured data
• Diagrams over walls of text — if it describes flow, structure, or relationships, add Mermaid

Step 3: Pick the diagram type and read its guide

Before creating any Mermaid diagram: read references/mermaid_style_guide.md.

Then open the specific type file (e.g., references/diagrams/flowchart.md) for the exemplar, tips, and copy-paste template.

Add accessibility metadata for types that emit it in the chosen renderer:

accTitle: Short Name 3-8 Words
accDescr: One or two sentences explaining what this diagram shows.

• Prefer host themes; %%{init} directives are deprecated in favor of YAML configuration
• Prefer reusable classDef where supported; style syntax is diagram-specific
• One emoji per node max — at the start of the label
• Use descriptive IDs with the type's syntax: snake_case works for flowcharts; ER/class/state conventions differ

Step 4: Write the document

Start from the template. Apply the markdown style guide. Place diagrams inline with related text — not in a separate "Figures" section.

Render in the actual destination before delivery. Check its Mermaid version and

plugin requirements before choosing newer diagram types; [Git

… (full content is in the download package)