.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), community discussion, 2026-02-19

• 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

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.

.md

references/markdown_style_guide.md

• 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

references/mermaid_style_guide.md

references/diagrams/flowchart.md

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

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

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

accTitle

accDescr

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

radar-beta
...

• 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)

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

  ?

SuperiorByteWorks-LLC/agent-project

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