Alterlab Mermaid

---
name: alterlab-mermaid
description: Writes Markdown documents and text-based Mermaid diagrams (flowcharts, sequence, class, ER, gantt, state, and more) with full style guides, 24 diagram-type references, and 9 document templates. Use when a diagram or technical document should live as version-controllable Markdown/Mermaid text rather than a rendered image — READMEs, methods and pipeline diagrams, analysis or status reports, ADRs, and project docs that render natively on GitHub and GitLab. For AI-rendered publication schematics use alterlab-scientific-schematics; for manuscript prose use alterlab-scientific-writing; for plots of numeric data use alterlab-matplotlib. Part of the AlterLab Academic Skills suite.
allowed-tools: Read Write Edit Bash
license: Apache-2.0
compatibility: No API key, network, or runtime dependencies. Authoring is pure Markdown/Mermaid text; diagrams render natively on GitHub, GitLab, Notion, VS Code, and any Mermaid-aware viewer. Syntax checked against Mermaid 11.12 and 12.0 (current 12.0.0 as of 2026-09).
metadata:
  skill-author: AlterLab
  skill-source: https://github.com/SuperiorByteWorks-LLC/agent-project
  version: "1.1.1"
  last_updated: "2026-09-23"
  skill-contributors:
    - name: Clayton Young
      org: Superior Byte Works, LLC / @borealBytes
      role: Author and originator
    - name: AlterLab Team
      org: AlterLab
      role: Integration and community feedback
---

# Markdown and Mermaid Writing

## Overview

This skill teaches you — and enforces a standard for — creating scientific documentation
using **markdown with embedded Mermaid diagrams as the default and canonical format**.

The core bet: a relationship expressed as a Mermaid diagram inside a `.md` file is more
valuable than any image. It is text, so it diffs cleanly in git. It requires no build step.
It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses
fewer tokens than a prose description of the same relationship. And it can always be
converted to a polished image later — but the text version remains the source of truth.

> "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), 2026-02-19

## When to Use This Skill

Use this skill when:

- Writing **Markdown documentation** — READMEs, how-tos, decision records, project docs, status reports, analysis write-ups
- Producing **a structural or relational diagram** — workflows, data pipelines, architectures, timelines, schemas
- Generating **output that will be version-controlled** — if it's going into git, it should be Markdown
- Someone asks you to "add a diagram" or "visualize the relationship" inside a document — start with Mermaid

Don't start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams. Those are Phase 2 and Phase 3, used only when Mermaid cannot express what's needed (e.g., scatter plots with real data, photorealistic images), because a text diagram stays diffable and editable.

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Drafting or revising manuscript prose (introduction, methods, discussion) | `alterlab-scientific-writing` / `alterlab-paper-writer` |
| Polished, AI-rendered publication figure (PNG) of a schematic or architecture | `alterlab-scientific-schematics` |
| Plot of real numeric data (scatter, distributions, heatmaps) | `alterlab-matplotlib` / `alterlab-seaborn` |
| Converting PDFs, Office files, or web pages into Markdown | `alterlab-markitdown` |

## 🎨 The Source Format Philosophy

### Why text-based diagrams win

| What matters | Mermaid in Markdown | Python / AI Image |
| ----------------------------- | :-----------------: | :---------------: |
| Git diff readable | ✅ | ❌ binary blob |
| Editable without regenerating | ✅ | ❌ |
| Token efficient vs. prose | ✅ smaller | ❌ larger |
| Renders without a build step | ✅ | ❌ needs hosting |
| Parseable by AI without vision | ✅ | ❌ |
| Works in GitHub / GitLab / Notion | ✅ | ⚠️ if hosted |
| Accessible (screen readers) | ✅ accTitle/accDescr | ⚠️ needs alt text |
| Convertible to image later | ✅ anytime | — already image |

### The three-phase workflow

```mermaid
flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Phase 1 Mermaid in markdown is always required and is the source of truth. Phases 2 and 3 are optional downstream conversions for polished output.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
    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
    p1 -.->|"when needed"| 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
```

**Phase 1 is mandatory.** Even if you proceed to Phase 2 or 3, the Mermaid source stays committed.

### What Mermaid can express

This skill has a guide for 23 Mermaid diagram types plus a multi-diagram composition guide. Almost every scientific relationship fits one:

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

**Renderer versions matter.** GitHub, GitLab, Notion, and VS Code each bundle their own Mermaid release. Mermaid 12.0 (September 2026) switched flowchart, class, ER, state, and requirement diagrams to the ELK layout by default and made `redux-color`/`neo` the default theme and look for those plus sequence diagrams, so the same source can lay out and look different on a 12.x renderer than on an 11.x one — don't hand-tune spacing for one renderer. `xychart`, `block`, `sankey`, and `packet` dropped their `-beta` suffix in Mermaid 11.9–11.10; both spellings parse on current Mermaid, and the `-beta` forms used in this skill also work on older renderers. Newer types (for example `venn-beta`, `ishikawa-beta`, `wardley-beta`, `swimlane`, use case, `agentflow-beta`) have no guide here; check that the target renderer supports them before relying on one.

---

## 🔧 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

Before writing any `.md` file: read `references/markdown_style_guide.md`.

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
- **Cite everything** — every external claim gets a footnote `[^N]` with full URL
- **Bold sparingly** — max 2-3 bold terms per paragraph, never full sentences
- **Horizontal rule after every `</details>`** — mandatory
- **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.

Mandatory rules for every diagram:

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

- **No `%%{init}` directives** — breaks GitHub dark mode
- **No inline `style`** — use `classDef` only
- **One emoji per node max** — at the start of the label
- **`snake_case` node IDs** — match the label

### 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.

### Step 5: Commit as text

The `.md` file with embedded Mermaid is what gets committed. If you also generated a PNG or AI image, those are supplementary — the markdown is the source.

---

## ⚠️ Common pitfalls

### Radar chart syntax (`radar-beta`)

**WRONG:**
```mermaid
radar
title Example
x-axis ["A", "B", "C"]
"Series" : [1, 2, 3]
```

**CORRECT:**
```mermaid
radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3
```

- **Use `radar-beta`** not `radar` (the bare keyword doesn't exist)
- **Use `axis`** to define dimensions, **not** `x-axis`
- **Use `curve`** to define data series, **not** quoted labels with colon
- **`accTitle`/`accDescr` work** — put them on the lines after `radar-beta` (verified on Mermaid 11.12, 11.17, and 12.0)

### XY Chart vs Radar confusion

| Diagram | Keyword | Axis syntax | Data syntax |
| ------- | ------- | ----------- | ----------- |
| **XY Chart** (bars/lines) | `xychart-beta` | `x-axis ["Label1", "Label2"]` | `bar [10, 20]` or `line [10, 20]` |
| **Radar** (spider/web) | `radar-beta` | `axis id["Label"]` | `curve id["Label"]{10, 20}` |

### Forgetting `accTitle`/`accDescr` on supported types

Most diagram types render `accTitle`/`accDescr` as the SVG's accessible title and description. Mindmap, Sankey, and Block diagrams fail to parse with them, Treemap fails on older renderers (seen on Mermaid 11.12; accepted on 11.17 and 12.0), and Timeline and Kanban accept them but drop them (checked on Mermaid 11.12, 11.17, and 12.0). For those six, place a descriptive italic paragraph directly above the code block instead:

> _Mindmap of the literature landscape grouped by method family. Mindmaps do not support accTitle/accDescr._

```mermaid
mindmap
...
```

---

## 🔗 Integration with other skills

### With `alterlab-scientific-schematics`

`alterlab-scientific-schematics` generates AI-powered publication-quality images (PNG). Use the Mermaid diagram as the **brief** for the schematic:

```
Workflow:
1. Create the concept as Mermaid in .md (this skill — Phase 1)
2. Describe the same concept to alterlab-scientific-schematics for a polished PNG (Phase 3)
3. Commit both — the .md as source, the PNG as a supplementary figure
```

### With `alterlab-scientific-writing`

When `alterlab-scientific-writing` produces a manuscript, all diagrams and structural figures should use this skill's standards. The writing skill handles prose and citations; this skill handles visual structure.

```
Workflow:
1. Use alterlab-scientific-writing to draft the manuscript
2. For every figure that shows a workflow, architecture, or relationship:
   - Replace placeholder with a Mermaid diagram following this skill's guide
3. Use alterlab-scientific-schematics only for figures that truly need photorealistic/complex rendering
```

### With `alterlab-literature-review`

Literature review produces summaries with lots of relationship data. Use this skill to:

- Create concept maps (Mindmap) of the literature landscape
- Show publication timelines (Timeline or Gantt)
- Compare methodologies (Quadrant or Radar)
- Diagram data flows described in papers (Sequence or Flowchart)

### With any skill that produces output documents

Before finalizing any document from any skill, apply this skill's checklist:

- [ ] Does the document use a template? If so, did I start from the right one?
- [ ] Are all diagrams in Mermaid with `accTitle` + `accDescr` (or an italic description for the six types that can't take them)?
- [ ] No `%%{init}`, no inline `style`, only `classDef`?
- [ ] Are all external claims cited with `[^N]`?
- [ ] One H1, emoji on H2 only?
- [ ] Horizontal rules after every `</details>`?

---

## 📚 Reference index

### Style guides

| Guide | Path | Lines | What it covers |
| ----------------------- | ------------------------------------------- | ----- | -------------------------------------------------- |
| Markdown Style Guide | `references/markdown_style_guide.md` | ~733 | Headings, formatting, citations, tables, Mermaid integration, templates, quality checklist |
| Mermaid Style Guide | `references/mermaid_style_guide.md` | ~458 | Accessibility, emoji set, color classes, theme neutrality, type selection, complexity tiers |

### Diagram type guides (24 types)

Each file contains: production-quality exemplar, tips specific to that type, and a copy-paste template.

`references/diagrams_` — architecture, block, c4, class, complex\_examples, er, flowchart, gantt, git\_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user\_journey, xy\_chart, zenuml

### Document templates (9 types)

`templates/` — decision\_record, how\_to\_guide, issue, kanban, presentation, project\_documentation, pull\_request, research\_paper, status\_report

### Examples

`assets/examples/example-research-report.md` — a complete scientific research report demonstrating proper heading hierarchy, multiple diagram types (flowchart, sequence, gantt), tables, footnote citations, collapsible sections, and all style guide rules applied.

---

## 📝 Attribution

All style guides, diagram type guides, and document templates in this skill are ported from the `SuperiorByteWorks-LLC/agent-project` repository under the Apache-2.0 License.

- **Source**: https://github.com/SuperiorByteWorks-LLC/agent-project
- **Author**: Clayton Young / Superior Byte Works, LLC (@borealBytes)
- **License**: Apache-2.0

This skill is licensed **Apache-2.0** (its frontmatter `license`) because most of its content is ported from the Apache-2.0 source above; the AlterLab Academic Skills repository as a whole is MIT-licensed (see `THIRD_PARTY_NOTICES.md`). Keep the attribution headers in the ported files, and include the Apache-2.0 license text when redistributing this skill on its own. Changes made here are recorded in the repository's CHANGELOG.

---

[^1]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[^2]: Mermaid. "Mermaid Diagramming and Charting Tool." https://mermaid.js.org/