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

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

• Creating any scientific document — reports, analyses, manuscripts, methods sections
• Writing any documentation — READMEs, how-tos, decision records, project docs
• Producing any diagram — workflows, data pipelines, architectures, timelines, relationships
• Generating any output that will be version-controlled — if it's going into git, it should be markdown
• Working with any other skill — this skill defines the documentation layer that wraps every other output
• Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always

Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams. Those are Phase 2 and Phase 3 — only used when Mermaid cannot express what's needed (e.g., scatter plots with real data, photorealistic images).

🎨 The Source Format Philosophy

Why text-based diagrams win

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:

references/diagrams/flowchart.md

references/diagrams/sequence.md

references/diagrams/er.md

references/diagrams/state.md

references/diagrams/gantt.md

references/diagrams/pie.md

references/diagrams/c4.md

references/diagrams/mindmap.md

references/diagrams/timeline.md

references/diagrams/class.md

references/diagrams/user_journey.md

references/diagrams/quadrant.md

references/diagrams/requirement.md

references/diagrams/sankey.md

references/diagrams/xy_chart.md

references/diagrams/block.md

references/diagrams/kanban.md

references/diagrams/architecture.md

references/diagrams/radar.md

references/diagrams/treemap.md

references/diagrams/packet.md

references/diagrams/git_graph.md

references/diagrams/zenuml.md

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:

templates/pull_request.md

templates/issue.md

templates/kanban.md

templates/decision_record.md

templates/presentation.md

templates/research_paper.md

templates/project_documentation.md

templates/how_to_guide.md

templates/status_report.md

Step 2: Read the style guide

Before writing any

.md

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

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

⚠️ 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

xychart-beta

x-axis ["Label1", "Label2"]

bar [10, 20]

line [10, 20]

radar-beta

axis id["Label"]

curve id["Label"]{10, 20}

Forgetting

accTitle

/

accDescr

on supported types

Only some diagram types support

accTitle

accDescr

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

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

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

references/markdown_style_guide.md

references/mermaid_style_guide.md

Diagram type guides (24 types)

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

references/diagrams/

Document templates (9 types)

templates/

Examples

assets/examples/example-research-report.md

📝 Attribution

All style guides, diagram type guides, and document templates in this skill are ported from the

SuperiorByteWorks-LLC/agent-project

• 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 scientific-agent-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.