# Markdown Mermaid Writing

Comprehensive markdown and Mermaid diagram writing skill.

- Repository: https://github.com/LeonChaoX/qinyan-academic-skills (996 stars)
- Category: Data and ML
- License: Apache-2.0
- Last updated: 2026-07-20
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add LeonChaoX/qinyan-academic-skills --skill markdown-mermaid-writing -g -a claude-code -y`
Codex: `npx skills add LeonChaoX/qinyan-academic-skills --skill markdown-mermaid-writing -g -a codex -y`
Cursor: `npx skills add LeonChaoX/qinyan-academic-skills --skill markdown-mermaid-writing -g -a cursor -y`
Gemini CLI: `npx skills add LeonChaoX/qinyan-academic-skills --skill markdown-mermaid-writing -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/LeonChaoX/qinyan-academic-skills/blob/HEAD/skills/03-学术演示与可视化/markdown-mermaid-writing/SKILL.md