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 templ

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), 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 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 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 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 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: 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: CORRECT: 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. 🔗 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: 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. 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 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. [^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/

markdown-mermaid-writing