markdown-mermaid-writing

name	markdown-mermaid-writing
description	Comprehensive markdown and Mermaid diagram writing skill. Use when creating any scientific document, report, analysis, or visualization. Establishes text-based diagrams as the default documentation standard with full style guides (markdown + mermaid), 24 diagram type references, and 9 document templates.
allowed-tools	Read Write Edit Bash
license	Apache-2.0
tags	["scientific-skills","markdown-mermaid-writing","writing","documentation","mermaid","diagram","visualization","citation-management"]
metadata	{"skill-author":"Clayton Young / Superior Byte Works, LLC (@borealBytes)","skill-source":"https://github.com/SuperiorByteWorks-LLC/agent-project","skill-version":"1.0.0","skill-contributors":[{"name":"Clayton Young","org":"Superior Byte Works, LLC / @borealBytes","role":"Author and originator"},{"name":"K-Dense Team","org":"K-Dense Inc.","role":"Integration target and community feedback"}]}

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

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

Mermaid covers 24 diagram types. 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

💡 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

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:

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

CORRECT:

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
• No accTitle/accDescr — radar-beta doesn't support accessibility annotations; always add a descriptive italic paragraph above the diagram

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

Only some diagram types support accTitle/accDescr. For those that don't, always place a descriptive italic paragraph directly above the code block:

Radar chart comparing three methods across five performance dimensions. Note: Radar charts do not support accTitle/accDescr.

radar-beta
...

---

🔗 Integration with other skills

With scientific-schematics

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 scientific-schematics for a polished PNG (Phase 3)
3. Commit both — the .md as source, the PNG as a supplementary figure

With scientific-writing

When 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 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 scientific-schematics only for figures that truly need photorealistic/complex rendering

With 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?
• 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 (as part of claude-scientific-skills) is distributed under the MIT License. The included Apache-2.0 content is compatible for downstream use with attribution retained, as preserved in the file headers throughout this skill.

---