# markdown-mermaid-writing

> Comprehensive markdown and Mermaid diagram writing skill establishing text-based diagrams as the default documentation standard, with full style guides, 24 diagram type references, and 9 document templates for scientific documents and reports.

**Use case**: Create scientific documents with embedded Mermaid diagrams

**Canonical URL**: https://agentcookbooks.com/skills/markdown-mermaid-writing/

**Topics**: claude-code, skills, science, scientific-writing

**Trigger phrases**: "write a document with diagrams", "create a Mermaid flowchart", "diagram this workflow", "write a technical report", "make a sequence diagram"

**Source**: [K-Dense AI](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/markdown-mermaid-writing)

**License**: Apache-2.0

---

## What it does

`markdown-mermaid-writing` is a Claude Code skill from K-Dense AI's [scientific-agent-skills repo](https://github.com/K-Dense-AI/scientific-agent-skills). It turns Claude into a document author that treats text-based Mermaid diagrams as the default visualization format for any scientific document, report, or analysis — rather than reaching for Python plotting libraries for structural diagrams.

A session produces a complete markdown document with embedded Mermaid diagrams (flowcharts, sequence diagrams, class diagrams, Gantt charts, ER diagrams, and 20 more types) following a consistent style guide, chosen from 9 document templates that cover common scientific communication needs.

The skill was authored by Clayton Young / Superior Byte Works, LLC and distributed through the K-Dense AI collection.

## When to use it

Reach for it when:

- You're documenting a workflow, pipeline, or system architecture and want a portable diagram that renders in GitHub, Notion, or any Markdown viewer
- You need to produce a structured report (analysis, protocol, project plan) and want diagrams embedded directly in the document rather than as external image files
- You're writing technical documentation where version-controllable, text-based diagrams matter

When *not* to reach for it:

- Publication-quality data plots — use `matplotlib`, `seaborn`, or `scientific-visualization`
- AI-generated photorealistic images or schematics — use `scientific-schematics` or `generate-image`

## Install

Copy the `SKILL.md` from K-Dense AI's [markdown-mermaid-writing folder](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/markdown-mermaid-writing) into `.claude/skills/markdown-mermaid-writing/` in your project.

Trigger phrases: "write a document with diagrams", "create a Mermaid flowchart", "diagram this workflow", "write a technical report".

## What a session looks like

A typical session has three phases:

1. **Template selection.** Claude identifies the document type from your description and selects the appropriate template (lab report, protocol, analysis report, project plan, etc.).
2. **Content and diagram drafting.** Document sections are written in parallel with Mermaid diagram blocks. Diagram type is chosen from the 24-type reference based on what best represents the structure you're describing.
3. **Style pass.** Claude applies the markdown style guide — consistent heading hierarchy, code block formatting, link syntax, and diagram theming — before returning the final document.

## Receipts

**Where it works well:**
- Workflow documentation for multi-step lab protocols where a flowchart conveys branching logic far better than prose
- Meeting notes and project plans where Gantt charts or timeline diagrams are embedded directly in the markdown file

**Where it backfires:**
- Diagrams that require pixel-level precision or exact layout control — Mermaid's auto-layout sometimes produces visually awkward results for complex graphs
- Environments that don't render Mermaid (e.g., plain-text email, some PDF renderers) lose the diagrams entirely

**Pattern that works:** generate the Mermaid source first and preview it in a renderer (GitHub preview, mermaid.live) before embedding it in the final document — the auto-layout can surprise you.

## Source and attribution

Skill authored by Clayton Young / Superior Byte Works, LLC (@borealBytes). The canonical SKILL.md lives in the [`markdown-mermaid-writing` folder](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/markdown-mermaid-writing) of K-Dense AI's scientific-agent-skills repository.

License: Apache-2.0. Install, adapt, and redistribute with attribution preserved.

This page documents the skill from a practitioner's perspective. For the formal spec and any updates, defer to the source repo.