markdown-mermaid-writing

Name: markdown-mermaid-writing
Author: K-Dense-AI

31kstars3.1kforks

How to install markdown-mermaid-writing?

k-dense-ai/scientific-agent-skills/markdown-mermaid-writing

$npx -y skills add K-Dense-AI/scientific-agent-skills --skill markdown-mermaid-writing

Installs into the current project.

Summary

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,

Files · 1

View on GitHub

SKILL.md

1	# Markdown and Mermaid Writing
2
3	## Overview
4
5	This skill teaches you — and enforces a standard for — creating scientific documentation
6	using markdown with embedded Mermaid diagrams as the default and canonical format.
7
8	The core bet: a relationship expressed as a Mermaid diagram inside a `.md` file is more
9	valuable than any image. It is text, so it diffs cleanly in git. It requires no build step.
10	It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses
11	fewer tokens than a prose description of the same relationship. And it can always be
12	converted to a polished image later — but the text version remains the source of truth.
13
14	> "The more you get your reports and files in .md in just regular text, which mermaid is
15	> as well as being a simple 'script language'. This just helps with any downstream rendering
16	> and especially AI generated images (using mermaid instead of just long form text to
17	> describe relationships < tokens). Additionally mermaid can render along with markdown for
18	> easy use almost anywhere by humans or AI."
19	>
20	> — Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19
21
22	## When to Use This Skill
23
24	Use this skill when:
25
26	- Creating any scientific document — reports, analyses, manuscripts, methods sections
27	- Writing any documentation — READMEs, how-tos, decision records, project docs
28	- Producing any diagram — workflows, data pipelines, architectures, timelines, relationships
29	- Generating any output that will be version-controlled — if it's going into git, it should be markdown
30	- Working with any other skill — this skill defines the documentation layer that wraps every other output
31	- Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always
32
33	Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams.
34	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).
35
36	## 🎨 The Source Format Philosophy
37
38	### Why text-based diagrams win
39
40	\| What matters \| Mermaid in Markdown \| Python / AI Image \|
41	\| ----------------------------- \| :-----------------: \| :---------------: \|
42	\| Git diff readable \| ✅ \| ❌ binary blob \|
43	\| Editable without regenerating \| ✅ \| ❌ \|
44	\| Token efficient vs. prose \| ✅ smaller \| ❌ larger \|
45	\| Renders without a build step \| ✅ \| ❌ needs hosting \|
46	\| Parseable by AI without vision \| ✅ \| ❌ \|
47	\| Works in GitHub / GitLab / Notion \| ✅ \| ⚠️ if hosted \|
48	\| Accessible (screen readers) \| ✅ accTitle/accDescr \| ⚠️ needs alt text \|
49	\| Convertible to image later \| ✅ anytime \| — already image \|
50
51	### The three-phase workflow
52
53	```mermaid
54	flowchart LR
55	accTitle: Three-Phase Documentation Workflow
56	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.
57
58	p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
59	p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
60	p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
61	out["📊 Final Deliverable"]
62
63	p1 --> out
64	p1 -.->\|"when needed"\| p2
65	p1 -.->\|"when needed"\| p3
66	p2 --> out
67	p3 --> out
68
69	classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
70	classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
71	classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
72
73	class p1 required
74	class p2,p3 optional
75	class out output
76	```
77
78	Phase 1 is mandatory. Even if you proceed to Phase 2 or 3, the Mermaid source stays committed.
79
80	### What Mermaid can express
81
82	Mermaid covers 24 diagram types. Almost every scientific relationship fits one:
83
84	\| Use case \| Diagram type \| File \|
85	\| -------------------------------------------- \| ---------------- \| ---------------------------------------------------- \|
86	\| Experimental workflow / decision logic \| Flowchart \| `references/diagrams/flowchart.md` \|
87	\| Service interactions / API calls / messaging \| Sequence \| `references/diagrams/sequence.md` \|
88	\| Data model / schema \| ER diagram \| `references/diagrams/e

People who liked this also viewed

6 picks

Type

markdown-mermaid-writing

31kstars3.1kforks

View on GitHub

How to install markdown-mermaid-writing?

k-dense-ai/scientific-agent-skills/markdown-mermaid-writing

$npx -y skills add K-Dense-AI/scientific-agent-skills --skill markdown-mermaid-writing

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Markdown and Mermaid Writing
2
3	## Overview
4
5	This skill teaches you — and enforces a standard for — creating scientific documentation
6	using markdown with embedded Mermaid diagrams as the default and canonical format.
7
8	The core bet: a relationship expressed as a Mermaid diagram inside a `.md` file is more
9	valuable than any image. It is text, so it diffs cleanly in git. It requires no build step.
10	It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses
11	fewer tokens than a prose description of the same relationship. And it can always be
12	converted to a polished image later — but the text version remains the source of truth.
13
14	> "The more you get your reports and files in .md in just regular text, which mermaid is
15	> as well as being a simple 'script language'. This just helps with any downstream rendering
16	> and especially AI generated images (using mermaid instead of just long form text to
17	> describe relationships < tokens). Additionally mermaid can render along with markdown for
18	> easy use almost anywhere by humans or AI."
19	>
20	> — Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19
21
22	## When to Use This Skill
23
24	Use this skill when:
25
26	- Creating any scientific document — reports, analyses, manuscripts, methods sections
27	- Writing any documentation — READMEs, how-tos, decision records, project docs
28	- Producing any diagram — workflows, data pipelines, architectures, timelines, relationships
29	- Generating any output that will be version-controlled — if it's going into git, it should be markdown
30	- Working with any other skill — this skill defines the documentation layer that wraps every other output
31	- Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always
32
33	Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams.
34	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).
35
36	## 🎨 The Source Format Philosophy
37
38	### Why text-based diagrams win
39
40	\| What matters \| Mermaid in Markdown \| Python / AI Image \|
41	\| ----------------------------- \| :-----------------: \| :---------------: \|
42	\| Git diff readable \| ✅ \| ❌ binary blob \|
43	\| Editable without regenerating \| ✅ \| ❌ \|
44	\| Token efficient vs. prose \| ✅ smaller \| ❌ larger \|
45	\| Renders without a build step \| ✅ \| ❌ needs hosting \|
46	\| Parseable by AI without vision \| ✅ \| ❌ \|
47	\| Works in GitHub / GitLab / Notion \| ✅ \| ⚠️ if hosted \|
48	\| Accessible (screen readers) \| ✅ accTitle/accDescr \| ⚠️ needs alt text \|
49	\| Convertible to image later \| ✅ anytime \| — already image \|
50
51	### The three-phase workflow
52
53	```mermaid
54	flowchart LR
55	accTitle: Three-Phase Documentation Workflow
56	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.
57
58	p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
59	p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
60	p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
61	out["📊 Final Deliverable"]
62
63	p1 --> out
64	p1 -.->\|"when needed"\| p2
65	p1 -.->\|"when needed"\| p3
66	p2 --> out
67	p3 --> out
68
69	classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
70	classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
71	classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
72
73	class p1 required
74	class p2,p3 optional
75	class out output
76	```
77
78	Phase 1 is mandatory. Even if you proceed to Phase 2 or 3, the Mermaid source stays committed.
79
80	### What Mermaid can express
81
82	Mermaid covers 24 diagram types. Almost every scientific relationship fits one:
83
84	\| Use case \| Diagram type \| File \|
85	\| -------------------------------------------- \| ---------------- \| ---------------------------------------------------- \|
86	\| Experimental workflow / decision logic \| Flowchart \| `references/diagrams/flowchart.md` \|
87	\| Service interactions / API calls / messaging \| Sequence \| `references/diagrams/sequence.md` \|
88	\| Data model / schema \| ER diagram \| `references/diagrams/e

People who liked this also viewed

6 picks

Type