markdown-mermaid-writing

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• write a document with diagrams
• create a Mermaid flowchart
• diagram this workflow
• write a technical report
• make a sequence diagram

What it does

markdown-mermaid-writing is a Claude Code skill from K-Dense AI’s scientific-agent-skills repo. 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 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 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.