＋ Add to collection

Install (CLI)

npx skillmds add k-dense-ai/markdown-mermaid-writing

Or Copy and Paste in Your Agent chat

Please install the Agent Skill "k-dense-ai/markdown-mermaid-writing" for me from skillmd.com. A SkillMD skill is a SKILL.md file — plain markdown plus a few companion files — that you save into my skills directory. Use whichever fetch route fits your setup: (1) if you have a terminal, run npx -y skillmds add k-dense-ai/markdown-mermaid-writing; (2) otherwise fetch the file manifest at https://api.skillmd.com/api/skills/k-dense-ai/markdown-mermaid-writing/bundle?format=manifest and download each listed file from its "url" into markdown-mermaid-writing/ in your skills directory; (3) if the SkillMD MCP tools are connected, call skillmd_download with slug "k-dense-ai/markdown-mermaid-writing" and save the returned files under markdown-mermaid-writing/. Show me the SKILL.md before saving if you'd like me to review it. If your skills directory is read-only (e.g. the Claude desktop app), save the files to a working folder instead and tell me — I'll add them through my app's skills settings.

README badge

Show this skill's registry status in your repo:

[![SkillMD](https://skillmd.com/badge/k-dense-ai/markdown-mermaid-writing.svg)](https://skillmd.com/skills/k-dense-ai/markdown-mermaid-writing)

markdown-mermaid-writing

Name: markdown-mermaid-writing
Rating: 4.2 (5 reviews)
Author: K-Dense AI

k-dense-ai/markdown-mermaid-writing · Agent Skill (multi-file)

by K-Dense AI · bundle

Published Jul 5, 2026 · Last updated Jul 6, 2026

Creates scientific documentation using markdown with embedded Mermaid diagrams as the default format, enforcing a text-based diagram standard with style guides, 24 diagram type references, and document templates.

SKILL.md

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

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

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

---
name: markdown-mermaid-writing
description: Creates scientific documentation using markdown with embedded Mermaid diagrams as the default format, enforcing a text-based diagram standard with style guides, 24 diagram type references, and document templates.
license: Apache-2.0
---

# 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

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

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:

```
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
- **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._

```mermaid
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 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/

Files

This skill is a package of 37 files. Install with the command above, or download the folder.

📄SKILL.md entry
📁assets
📁examples
📄example-research-report.md 8.8 KB
📁references
📁diagrams
📄architecture.md 4.3 KB
📄block.md 4.7 KB
📄c4.md 6.1 KB
📄class.md 8.3 KB
📄complex_examples.md 16.7 KB
📄er.md 7.4 KB
📄flowchart.md 6.8 KB
📄gantt.md 5.7 KB
📄git_graph.md 2.0 KB
📄kanban.md 3.5 KB
📄mindmap.md 2.2 KB
📄packet.md 1.7 KB
📄pie.md 1.5 KB
📄quadrant.md 2.1 KB
📄radar.md 2.1 KB
📄requirement.md 2.4 KB
📄sankey.md 2.1 KB
📄sequence.md 5.4 KB
📄state.md 5.3 KB
📄timeline.md 4.1 KB
📄treemap.md 2.0 KB
📄user_journey.md 4.9 KB
📄xy_chart.md 1.8 KB
📄zenuml.md 2.2 KB
📄markdown_style_guide.md 34.3 KB
📄mermaid_style_guide.md 25.8 KB
📁templates
📄decision_record.md 7.0 KB
📄how_to_guide.md 6.9 KB
📄issue.md 12.5 KB
📄kanban.md 11.1 KB
📄presentation.md 7.9 KB
📄project_documentation.md 11.2 KB
📄pull_request.md 12.6 KB
📄research_paper.md 9.9 KB
📄status_report.md 7.0 KB

K-Dense-AI/scientific-agent-skills/tree/main/skills/markdown-mermaid-writing commit · 26fd7a8451

▌
wiki-page-writer · microsoft
Generates rich technical documentation pages with dark-mode Mermaid diagrams, source code citations, and first-principles depth.

2.7k
repo stars
▌
mermaidjs-v11 · dangquangse bundle
Create text-based diagrams and visualizations using Mermaid.js v11 syntax, covering flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, and more. Includes CLI conversion to SVG/PNG/PDF, JavaScript integration, theming, and configuration options.

19
repo stars
▌
mermaidjs-v11 · huuanh20 bundle
Create text-based diagrams with Mermaid.js v11 syntax, covering flowcharts, sequence diagrams, class diagrams, and more. Convert to SVG, PNG, or PDF via CLI, or embed in web pages with JavaScript.

1
repo stars
▌
explain-diff-html · moonklabs bundle
Generates interactive HTML explainers for code diffs, branches, and PRs from a single Markdown document, using a renderer to produce styled output with diagrams and quizzes.

0
repo stars
▌
obsidian-markdown · kepano bundle
Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax.

39.8k
repo stars
▌
wiki-vitepress · microsoft
Packages generated wiki Markdown into a VitePress static site with dark theme, dark-mode Mermaid diagrams with click-to-zoom, and production build output.

2.7k
repo stars

Frequently asked questions

How do I install the markdown-mermaid-writing skill?

Run npx skillmds add k-dense-ai/markdown-mermaid-writing in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the markdown-mermaid-writing skill do?

Is markdown-mermaid-writing safe to use?

SkillMD's automated safety review verdict for this skill is PASS. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with markdown-mermaid-writing?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is markdown-mermaid-writing free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.

Who published markdown-mermaid-writing?

K-Dense AI (@k-dense-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.