alterlab-mermaid

name	alterlab-mermaid
description	Writes Markdown documents and text-based Mermaid diagrams (flowcharts, sequence, class, ER, gantt, state, and more) with full style guides, 24 diagram-type references, and 9 document templates. Use when authoring a scientific document, report, analysis, or README, or when a diagram should be expressed as version-controllable Mermaid/Markdown text rather than a rendered image. For AI-rendered publication schematics use scientific-schematics instead. Part of the AlterLab Academic Skills suite.
allowed-tools	Read Write Edit Bash
license	Apache-2.0
compatibility	No API key, network, or runtime dependencies. Authoring is pure Markdown/Mermaid text; diagrams render natively on GitHub, GitLab, Notion, VS Code, and any Mermaid-aware viewer.
metadata	{"skill-author":"AlterLab","skill-source":"https://github.com/SuperiorByteWorks-LLC/agent-project","version":"1.0.0","skill-contributors":[{"name":"Clayton Young","org":"Superior Byte Works, LLC / @borealBytes","role":"Author and originator"},{"name":"AlterLab Team","org":"AlterLab","role":"Integration and community feedback"}]}

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), 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	✅	❌