Voice & style·Learning & Documentation

Markdown and Mermaid Writing

Name: Markdown and Mermaid Writing
Author: K-Dense-AI

Comprehensive markdown and Mermaid diagram writing skill.

You say

Install this skill Read the source first Free Written by K-Dense-AI · unverified publisher

Context cost: 70.4k tokensestimated from the bundle, loaded when it triggers
Bundle: 37 files · 281.7 kBtext throughout, nothing executable
Licence: Apache-2.0free to use
Last change: —no release on file
Servers it uses: Noneruns standalone

What it does

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.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Voice & style

Changes how the agent writes and reviews.

documentationwriting

Filed under

Learning & Documentation

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md14.9 kB · 328 lines

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

19# Markdown and Mermaid Writing

21## Overview

23This skill teaches you — and enforces a standard for — creating scientific documentation

24using **markdown with embedded Mermaid diagrams as the default and canonical format**.

26The core bet: a relationship expressed as a Mermaid diagram inside a .md file is more

27valuable than any image. It is text, so it diffs cleanly in git. It requires no build step.

28It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses

29fewer tokens than a prose description of the same relationship. And it can always be

30converted to a polished image later — but the text version remains the source of truth.

32> "The more you get your reports and files in .md in just regular text, which mermaid is

33> as well as being a simple 'script language'. This just helps with any downstream rendering

34> and especially AI generated images (using mermaid instead of just long form text to

35> describe relationships < tokens). Additionally mermaid can render along with markdown for

36> easy use almost anywhere by humans or AI."

37>

38> — Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

40## When to Use This Skill

42Use this skill when:

44- Creating **any scientific document** — reports, analyses, manuscripts, methods sections

45- Writing **any documentation** — READMEs, how-tos, decision records, project docs

46- Producing **any diagram** — workflows, data pipelines, architectures, timelines, relationships

47- Generating **any output that will be version-controlled** — if it's going into git, it should be markdown

48- Working with **any other skill** — this skill defines the documentation layer that wraps every other output

49- Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always

51Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams.

52Those are Phase 2 and Phase 3 — only used when Mermaid cannot express what's needed (e.g., scatter plots with real data, photorealistic images).

54## 🎨 The Source Format Philosophy

56### Why text-based diagrams win

58| What matters | Mermaid in Markdown | Python / AI Image |

59| ----------------------------- | :-----------------: | :---------------: |

60| Git diff readable | ✅ | ❌ binary blob |

61| Editable without regenerating | ✅ | ❌ |

62| Token efficient vs. prose | ✅ smaller | ❌ larger |

63| Renders without a build step | ✅ | ❌ needs hosting |

64| Parseable by AI without vision | ✅ | ❌ |

65| Works in GitHub / GitLab / Notion | ✅ | ⚠️ if hosted |

66| Accessible (screen readers) | ✅ accTitle/accDescr | ⚠️ needs alt text |

67| Convertible to image later | ✅ anytime | — already image |

69### The three-phase workflow

71```mermaid

72flowchart LR

73 accTitle: Three-Phase Documentation Workflow

74 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.

76 p1["📄 Phase 1 Mermaid in Markdown (ALWAYS — source of truth)"]

77 p2["🐍 Phase 2 Python Generated (optional — data charts)"]

78 p3["🎨 Phase 3 AI Generated Visuals (optional — polish)"]

79 out["📊 Final Deliverable"]

81 p1 --> out

82 p1 -.->|"when needed"| p2

83 p1 -.->|"when needed"| p3

84 p2 --> out

85 p3 --> out

87 classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f

88 classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12

89 classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

91 class p1 required

92 class p2,p3 optional

93 class out output

94```

96**Phase 1 is mandatory.** Even if you proceed to Phase 2 or 3, the Mermaid source stays committed.

98### What Mermaid can express

100Mermaid covers 24 diagram types. Almost every scientific relationship fits one:

101

102| Use case | Diagram type | File |

103| -------------------------------------------- | ---------------- | ---------------------------------------------------- |

104| Experimental workflow / decision logic | Flowchart | references/diagrams/flowchart.md |

105| Service interactions / API calls / messaging | Sequence | references/diagrams/sequence.md |

106| Data model / schema | ER diagram | references/diagrams/er.md |

107| State machine / lifecycle | State | references/diagrams/state.md |

108| Project timeline / roadmap | Gantt | references/diagrams/gantt.md |

109| Proportions / composition | Pie | references/diagrams/pie.md |

110| System architecture (zoom levels) | C4 | references/diagrams/c4.md |

111| Concept hierarchy / brainstorm | Mindmap | references/diagrams/mindmap.md |

112| Chronological events / history | Timeline | references/diagrams/timeline.md |

113| Class hierarchy / type relationships | Class | references/diagrams/class.md |

114| User journey / satisfaction map | User Journey | references/diagrams/user_journey.md |

115| Two-axis comparison / prioritization | Quadrant | references/diagrams/quadrant.md |

116| Requirements traceability | Requirement | references/diagrams/requirement.md |

117| Flow magnitude / resource distribution | Sankey | references/diagrams/sankey.md |

118| Numeric trends / bar + line charts | XY Chart | references/diagrams/xy_chart.md |

119| Component layout / spatial arrangement | Block | references/diagrams/block.md |

120| Work item status / task columns | Kanban | references/diagrams/kanban.md |

121| Cloud infrastructure / service topology | Architecture | references/diagrams/architecture.md |

122| Multi-dimensional comparison / skills radar | Radar | references/diagrams/radar.md |

123| Hierarchical proportions / budget | Treemap | references/diagrams/treemap.md |

124| Binary protocol / data format | Packet | references/diagrams/packet.md |

125| Git branching / merge strategy | Git Graph | references/diagrams/git_graph.md |

126| Code-style sequence (programming syntax) | ZenUML | references/diagrams/zenuml.md |

127| Multi-diagram composition patterns | Complex Examples | references/diagrams/complex_examples.md |

128

129> 💡 **Pick the right type, not the easy one.** Don't default to flowcharts for everything.

130> A timeline beats a flowchart for chronological events. A sequence beats a flowchart for

131> service interactions. Scan the table and match.

132

133---

134

135## 🔧 Core workflow

136

137### Step 1: Identify the document type

138

139Check if a template exists before writing from scratch:

140

141| Document type | Template |

142| ------------------------------ | ----------------------------------------------- |

143| Pull request record | templates/pull_request.md |

144| Issue / bug / feature request | templates/issue.md |

145| Sprint / project board | templates/kanban.md |

146| Architecture decision (ADR) | templates/decision_record.md |

147| Presentation / briefing | templates/presentation.md |

148| Research paper / analysis | templates/research_paper.md |

149| Project documentation | templates/project_documentation.md |

150| How-to / tutorial | templates/how_to_guide.md |

151| Status report | templates/status_report.md |

152

153### Step 2: Read the style guide

154

155Before writing any .md file: read references/markdown_style_guide.md.

156

157Key rules to internalize:

158

159- **One H1 per document** — the title. Never more.

160- **Emoji on H2 headings only** — one emoji per H2, none in H3/H4

161- **Cite everything** — every external claim gets a footnote [^N] with full URL

162- **Bold sparingly** — max 2-3 bold terms per paragraph, never full sentences

163- **Horizontal rule after every </details>** — mandatory

164- **Tables over prose** for comparisons, configurations, structured data

165- **Diagrams over walls of text** — if it describes flow, structure, or relationships, add Mermaid

166

167### Step 3: Pick the diagram type and read its guide

168

169Before creating any Mermaid diagram: read references/mermaid_style_guide.md.

170

171Then open the specific type file (e.g., references/diagrams/flowchart.md) for the exemplar, tips, and copy-paste template.

172

173Mandatory rules for every diagram:

174

175```

176accTitle: Short Name 3-8 Words

177accDescr: One or two sentences explaining what this diagram shows.

178```

179

180- **No %%{init} directives** — breaks GitHub dark mode

181- **No inline style** — use classDef only

182- **One emoji per node max** — at the start of the label

183- **snake_case node IDs** — match the label

184

185### Step 4: Write the document

186

187Start from the template. Apply the markdown style guide. Place diagrams inline with related text — not in a separate "Figures" section.

188

189### Step 5: Commit as text

190

191The .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.

192

193---

194

195## ⚠️ Common pitfalls

196

197### Radar chart syntax (radar-beta)

198

199**WRONG:**

200```mermaid

201radar

202title Example

203x-axis ["A", "B", "C"]

204"Series" : [1, 2, 3]

205```

206

207**CORRECT:**

208```mermaid

209radar-beta

210title Example

211axis a["A"], b["B"], c["C"]

212curve series["Series"]{1, 2, 3}

213max 3

214```

215

216- **Use radar-beta** not radar (the bare keyword doesn't exist)

217- **Use axis** to define dimensions, **not** x-axis

218- **Use curve** to define data series, **not** quoted labels with colon

219- **No accTitle/accDescr** — radar-beta doesn't support accessibility annotations; always add a descriptive italic paragraph above the diagram

220

221### XY Chart vs Radar confusion

222

224| ------- | ------- | ----------- | ----------- |

226| **Radar** (spider/web) | radar-beta | axis id["Label"] | curve id["Label"]{10, 20} |

227

228### Forgetting accTitle/accDescr on supported types

229

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

231

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

233

234```mermaid

235radar-beta

236...

237```

238

239---

240

241## 🔗 Integration with other skills

242

243### With scientific-schematics

244

245scientific-schematics generates AI-powered publication-quality images (PNG). Use the Mermaid diagram as the **brief** for the schematic:

246

247```

248Workflow:

2491. Create the concept as Mermaid in .md (this skill — Phase 1)

2502. Describe the same concept to scientific-schematics for a polished PNG (Phase 3)

2513. Commit both — the .md as source, the PNG as a supplementary figure

252```

253

254### With scientific-writing

255

256When 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.

257

258```

259Workflow:

2601. Use scientific-writing to draft the manuscript

2612. For every figure that shows a workflow, architecture, or relationship:

262 - Replace placeholder with a Mermaid diagram following this skill's guide

2633. Use scientific-schematics only for figures that truly need photorealistic/complex rendering

264```

265

266### With literature-review

267

268Literature review produces summaries with lots of relationship data. Use this skill to:

269

270- Create concept maps (Mindmap) of the literature landscape

271- Show publication timelines (Timeline or Gantt)

272- Compare methodologies (Quadrant or Radar)

273- Diagram data flows described in papers (Sequence or Flowchart)

274

275### With any skill that produces output documents

276

277Before finalizing any document from any skill, apply this skill's checklist:

278

279- [ ] Does the document use a template? If so, did I start from the right one?

280- [ ] Are all diagrams in Mermaid with accTitle + accDescr?

281- [ ] No %%{init}, no inline style, only classDef?

282- [ ] Are all external claims cited with [^N]?

283- [ ] One H1, emoji on H2 only?

284- [ ] Horizontal rules after every </details>?

285

286---

287

288## 📚 Reference index

289

290### Style guides

291

293| ----------------------- | ------------------------------------------- | ----- | -------------------------------------------------- |

296

297### Diagram type guides (24 types)

298

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

300

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

302

303### Document templates (9 types)

304

305templates/ — decision\_record, how\_to\_guide, issue, kanban, presentation, project\_documentation, pull\_request, research\_paper, status\_report

306

307### Examples

308

309assets/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.

310

311---

312

313## 📝 Attribution

314

315All 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.

316

317- **Source**: https://github.com/SuperiorByteWorks-LLC/agent-project

318- **Author**: Clayton Young / Superior Byte Works, LLC (@borealBytes)

319- **License**: Apache-2.0

320

321This 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.

322

323---

324

325[^1]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

326

327[^2]: Mermaid. "Mermaid Diagramming and Charting Tool." https://mermaid.js.org/

328

In the file

SKILL.md2,080 words

Files37

LicenceApache-2.0

Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈210

always loaded

The name and description, so the model knows the skill exists and when to reach for it.

70,215

on trigger

The instruction body and 36 supporting files, read only when the skill fires.

35.2%

of a 200k window

Ten skills this size would take about 352% of the window before you open a file.

050k100k150k200k context window

70.4k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Heavy. Teams tend to install this one per project rather than globally, and load it only when the job comes up.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption

Installsnone yet

Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It asks the agent to write files, using whatever file access your client already has. It never touches the network.

What it asks for

Writes filesyes

Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

If this is not it

45 other skills in Learning & Documentation

What is in the bundle

37 files, 281.7 kB on disk. A bundle is text throughout: the instructions the model reads, plus the templates it fills in.

SKILL.md14.9 kB
assets/examples/example-research-report.md9.0 kB
references/markdown_style_guide.md35.1 kB
references/mermaid_style_guide.md26.4 kB
references/diagrams/architecture.md4.4 kB
references/diagrams/block.md4.8 kB
references/diagrams/c4.md6.2 kB
references/diagrams/class.md8.5 kB
references/diagrams/complex_examples.md17.1 kB
references/diagrams/er.md7.6 kB
references/diagrams/flowchart.md7.0 kB
references/diagrams/gantt.md5.9 kB
references/diagrams/git_graph.md2.0 kB
references/diagrams/kanban.md3.5 kB
references/diagrams/mindmap.md2.2 kB
references/diagrams/packet.md1.7 kB
references/diagrams/pie.md1.6 kB
references/diagrams/quadrant.md2.2 kB
references/diagrams/radar.md2.2 kB
references/diagrams/requirement.md2.5 kB
references/diagrams/sankey.md2.1 kB
references/diagrams/sequence.md5.5 kB
references/diagrams/state.md5.5 kB
references/diagrams/timeline.md4.2 kB
references/diagrams/treemap.md2.0 kB
references/diagrams/user_journey.md5.0 kB
references/diagrams/xy_chart.md1.9 kB
references/diagrams/zenuml.md2.3 kB
templates/decision_record.md7.2 kB
templates/how_to_guide.md7.1 kB
templates/issue.md12.8 kB
templates/kanban.md11.4 kB
templates/presentation.md8.1 kB
templates/project_documentation.md11.5 kB
templates/pull_request.md12.9 kB
templates/research_paper.md10.2 kB
templates/status_report.md7.2 kB

What is not in it

No dependencies and nothing executable: a skill is text the agent reads, so the bundle is 37 files you can review in full before installing. The Apache-2.0 licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

# Markdown and Mermaid Writing · 70.4k tokens when loaded
npx mcprush@latest skill add k-dense-ai/markdown-and-mermaid-writing

Writes to .claude/skills/markdown-and-mermaid-writing/ in the current project. Add --global to put it in your home directory instead, for every project.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/

Claude Desktop

ChatGPT

Cursor.cursor/skills/

VS Code.github/skills/

Codex CLI.agents/skills/

Gemini CLI.gemini/skills/

Grok.grok/skills/

Zed.agents/skills/

Windsurf.windsurf/skills/

Agent SDK.claude/skills/

HTTP / API

This release

Versionnot versioned

Publishedno release date on file

PriceFree

Referencek-dense-ai/markdown-and-mermaid-writing

Versions

Its author publishes no version number, so there is nothing here to pin to: what you install is the folder as it stands today. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

No earlier releases have been published to the marketplace.

Pinning

Nothing to pin to: this skill carries no version number of its own. What you install is what the folder holds on the day you install it.

Reviews

—no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Who wrote it

K-Dense-AI

Publishes on mcprush.

0 servers listed3 skills listednot claimed

Profile

Publisher

Servers0

Claim this skill