跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

markdown-mermaid-writing

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.

LeonChaoX · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add LeonChaoX/qinyan-academic-skills --skill markdown-mermaid-writing

技能说明


name: markdown-mermaid-writing 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. allowed-tools: Read Write Edit Bash license: Apache-2.0 metadata: skill-author: Clayton Young / Superior Byte Works, LLC (@borealBytes) skill-source: https://github.com/SuperiorByteWorks-LLC/agent-project skill-version: "1.0.0" skill-contributors: - name: Clayton Young org: Superior Byte Works, LLC / @borealBytes role: Author and originator - name: K-Dense Team org: K-Dense Inc. role: Integration target 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), 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

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 mattersMermaid in MarkdownPython / AI Image
Git diff readable✅❌ binary blob
Editable without regenerating✅❌
Token efficient vs. prose✅ smaller❌ larger
Renders without a build step✅❌ needs hosting
Parseable by AI without vision✅❌
Works in GitHub / GitLab / Notion✅⚠️ if hosted
Accessible (screen readers)✅ accTitle/accDescr⚠️ needs alt text
Convertible to image later✅ anytime— already image

The three-phase workflow

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    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.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
    p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
    p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
    out["📊 Final Deliverable"]

    p1 --> out
    p1 -.->|"when needed"| p2
    p1 -.->|"when needed"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

Phase 1 is mandatory. Even if you proceed to Phase 2 or 3, the Mermaid source stays committed.

What Mermaid can express

Mermaid covers 24 diagram types. Almost every scientific relationship fits one:

Use caseDiagram typeFile
Experimental workflow / decision logicFlowchartreferences/diagrams/flowchart.md
Service interactions / API calls / messagingSequencereferences/diagrams/sequence.md
Data model / schemaER diagramreferences/diagrams/er.md
State machine / lifecycleStatereferences/diagrams/state.md
Project timeline / roadmapGanttreferences/diagrams/gantt.md
Proportions / compositionPiereferences/diagrams/pie.md
System architecture (zoom levels)C4references/diagrams/c4.md
Concept hierarchy / brainstormMindmapreferences/diagrams/mindmap.md
Chronological events / historyTimelinereferences/diagrams/timeline.md
Class hierarchy / type relationshipsClassreferences/diagrams/class.md
User journey / satisfaction mapUser Journeyreferences/diagrams/user_journey.md
Two-axis comparison / prioritizationQuadrantreferences/diagrams/quadrant.md
Requirements traceabilityRequirementreferences/diagrams/requirement.md
Flow magnitude / resource distributionSankeyreferences/diagrams/sankey.md
Numeric trends / bar + line chartsXY Chartreferences/diagrams/xy_chart.md
阅读完整来源 ↗