AI Skills
markdown-mermaid-writing

markdown-mermaid-writing

熱門

全方位的 Markdown 與 Mermaid 圖表撰寫技能。適用於建立任何科學文件、報告、分析或視覺化內容。以文字型圖表作為預設的文件標準，內含完整樣式指南（Markdown + Mermaid）、24 種圖表類型參考與 9 種文件範本。

3.8萬星標
3574分支
更新於 2026/8/29
獲取技能源代碼

相關技能

ito-baskets26萬writing-guidelines9.9萬recsys-pipeline-architect24萬
SKILL.md
唯讀
名稱
markdown-mermaid-writing
描述

全方位的 Markdown 與 Mermaid 圖表撰寫技能。適用於建立任何科學文件、報告、分析或視覺化內容。以文字型圖表作為預設的文件標準，內含完整樣式指南（Markdown + Mermaid）、24 種圖表類型參考與 9 種文件範本。

Markdown 與 Mermaid 撰寫

總覽

此技能教導你——並強制執行一套標準——建立科學文件，
使用內嵌 Mermaid 圖表的 Markdown 作為預設且標準的格式。

核心主張：以 .md 檔案中的 Mermaid 圖表來表達關係，比任何圖片都更有價值。
它是文字，因此在 git 中能乾淨地比對差異。它不需要建置步驟。
它能在 GitHub、GitLab、Notion、VS Code 以及任何 Markdown 檢視器中原生呈現。
比起用散文描述相同關係，它使用更少的 token。而且之後隨時可以轉換成精美的圖片——但文字版本永遠是事實來源。

「你越常把報告和檔案用 .md 的純文字格式呈現，而 Mermaid 正是如此，
同時也是一種簡單的『腳本語言』。這有助於任何下游渲染，
尤其是 AI 生成的圖片（用 Mermaid 描述關係比用長篇文字更省 token）。
此外，Mermaid 可以與 Markdown 一起渲染，幾乎在任何地方都能輕鬆供人類或 AI 使用。」

— Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

何時使用此技能

在以下情況使用此技能：

  • 建立任何科學文件——報告、分析、手稿、方法章節
  • 撰寫任何文件——README、操作指南、決策紀錄、專案文件
  • 製作任何圖表——工作流程、資料管線、架構、時間軸、關係圖
  • 產生任何會進行版本控制的輸出——如果要放進 git，就應該是 Markdown
  • 與任何其他技能搭配使用——此技能定義了包覆所有其他輸出的文件層
  • 有人要求你「加個圖表」或「視覺化關係」——一律優先使用 Mermaid

對於結構性或關係性圖表，請勿從 Python matplotlib、seaborn 或 AI 圖片生成開始。
那些是第二階段和第三階段——僅在 Mermaid 無法表達所需內容時使用（例如帶有真實數據的散佈圖、寫實圖片）。

🎨 來源格式哲學

為什麼文字型圖表勝出

重要事項 Markdown 中的 Mermaid Python / AI 圖片
Git 差異可讀 ✅ ❌ 二進位檔案
無需重新生成即可編輯 ✅ ❌
相較散文更省 token ✅ 較小 ❌ 較大
無需建置步驟即可渲染 ✅ ❌ 需要託管
AI 無需視覺即可解析 ✅ ❌
可在 GitHub / GitLab / Notion 運作 ✅ ⚠️ 需託管
無障礙（螢幕閱讀器） ✅ accTitle/accDescr ⚠️ 需要替代文字
之後可轉換為圖片 ✅ 隨時 — 已是圖片

三階段工作流程

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["📄 第一階段<br/>Markdown 中的 Mermaid<br/>（一律——事實來源）"]
    p2["🐍 第二階段<br/>Python 生成<br/>（選用——資料圖表）"]
    p3["🎨 第三階段<br/>AI 生成視覺<br/>（選用——精修）"]
    out["📊 最終交付物"]

    p1 --> out
    p1 -.->|"需要時"| p2
    p1 -.->|"需要時"| 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

第一階段是強制的。 即使你進入第二或第三階段，Mermaid 原始碼仍會保留在版本控制中。

Mermaid 能表達什麼

Mermaid 涵蓋 24 種圖表類型。幾乎所有科學關係都能對應到其中一種：

使用情境 圖表類型 檔案
實驗流程 / 決策邏輯 Flowchart references/diagrams/flowchart.md
服務互動 / API 呼叫 / 訊息傳遞 Sequence references/diagrams/sequence.md
資料模型 / 結構描述 ER diagram references/diagrams/er.md
狀態機 / 生命週期 State references/diagrams/state.md
專案時間軸 / 藍圖 Gantt references/diagrams/gantt.md
比例 / 組成 Pie references/diagrams/pie.md
系統架構（縮放層級） C4 references/diagrams/c4.md
概念階層 / 腦力激盪 Mindmap references/diagrams/mindmap.md
按時間順序的事件 / 歷史 Timeline references/diagrams/timeline.md
類別階層 / 型別關係 Class references/diagrams/class.md
使用者旅程 / 滿意度地圖 User Journey references/diagrams/user_journey.md
雙軸比較 / 優先排序 Quadrant references/diagrams/quadrant.md
需求追溯 Requirement references/diagrams/requirement.md
流量大小 / 資源分配 Sankey references/diagrams/sankey.md
數值趨勢 / 長條圖 + 折線圖 XY Chart references/diagrams/xy_chart.md
元件佈局 / 空間安排 Block references/diagrams/block.md
工作項目狀態 / 任務欄位 Kanban references/diagrams/kanban.md
雲端基礎設施 / 服務拓撲 Architecture references/diagrams/architecture.md
多維度比較 / 技能雷達 Radar references/diagrams/radar.md
階層式比例 / 預算 Treemap references/diagrams/treemap.md
二進位協定 / 資料格式 Packet references/diagrams/packet.md
Git 分支 / 合併策略 Git Graph references/diagrams/git_graph.md
程式碼風格序列（程式語法） ZenUML references/diagrams/zenuml.md
多圖表組合模式 Complex Examples references/diagrams/complex_examples.md

💡 選擇正確的類型，而不是簡單的類型。 不要什麼都用流程圖。
時間軸比流程圖更適合按時間順序的事件。序列圖比流程圖更適合服務互動。
瀏覽表格並對應。

🔧 核心工作流程

步驟 1：識別文件類型

在從零開始撰寫前，檢查是否有範本可用：

文件類型 範本
Pull request 紀錄 templates/pull_request.md
Issue / 錯誤 / 功能請求 templates/issue.md
Sprint / 專案看板 templates/kanban.md
架構決策（ADR） templates/decision_record.md
簡報 / 簡報資料 templates/presentation.md
研究論文 / 分析 templates/research_paper.md
專案文件 templates/project_documentation.md
操作指南 / 教學 templates/how_to_guide.md
狀態報告 templates/status_report.md

步驟 2：閱讀樣式指南

在撰寫任何 .md 檔案前：閱讀 references/markdown_style_guide.md。

需要內化的關鍵規則：

  • 每份文件一個 H1——標題。絕不超過一個。
  • 僅在 H2 標題使用表情符號——每個 H2 一個表情符號，H3/H4 不使用
  • 引用所有內容——每個外部主張都要有附完整 URL 的註腳 [^N]
  • 謹慎使用粗體——每段最多 2-3 個粗體詞，絕不用整個句子
  • 每個 </details> 後要有水平線——強制規定
  • 比較、設定、結構化資料用表格，而非散文
  • 圖表勝過文字牆——如果描述流程、結構或關係，就加入 Mermaid

步驟 3：選擇圖表類型並閱讀其指南

在建立任何 Mermaid 圖表前：閱讀 references/mermaid_style_guide.md。

然後開啟特定類型檔案（例如 references/diagrams/flowchart.md）查看範例、提示和可複製貼上的範本。

每個圖表的強制規則：

accTitle: 短名稱 3-8 個字
accDescr: 一兩句話說明此圖表顯示的內容。
  • 不使用 %%{init} 指令——會破壞 GitHub 深色模式
  • 不使用內聯 style——僅使用 classDef
  • 每個節點最多一個表情符號——放在標籤開頭
  • snake_case 節點 ID——與標籤對應

步驟 4：撰寫文件

從範本開始。套用 Markdown 樣式指南。將圖表放在相關文字內聯位置——不要放在獨立的「圖表」章節。

步驟 5：以文字形式提交

內嵌 Mermaid 的 .md 檔案才是要提交的內容。如果你也生成了 PNG 或 AI 圖片，那些是輔助性的——Markdown 才是來源。

⚠️ 常見陷阱

雷達圖語法（radar-beta）

錯誤：

radar
title Example
x-axis ["A", "B", "C"]
"Series" : [1, 2, 3]

正確：

radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3
  • 使用 radar-beta 而非 radar（單獨的關鍵字不存在）
  • 使用 axis 定義維度，不要用 x-axis
  • 使用 curve 定義資料系列，不要用帶冒號的引號標籤
  • 不使用 accTitle/accDescr——radar-beta 不支援無障礙註解；務必在圖表上方加上描述性的斜體段落

XY Chart 與 Radar 的混淆

圖表 關鍵字 軸語法 資料語法
XY Chart（長條圖/折線圖） xychart-beta x-axis ["Label1", "Label2"] bar [10, 20] 或 line [10, 20]
Radar（蜘蛛網圖） radar-beta axis id["Label"] curve id["Label"]{10, 20}

在支援的類型上忘記 accTitle/accDescr

只有部分圖表類型支援 accTitle/accDescr。對於不支援的類型，務必在程式碼區塊正上方放置描述性的斜體段落：

雷達圖比較三種方法在五個效能維度上的表現。注意：雷達圖不支援 accTitle/accDescr。

radar-beta
...

🔗 與其他技能的整合

與 scientific-schematics 搭配

scientific-schematics 會生成 AI 驅動的出版品質圖片（PNG）。將 Mermaid 圖表作為示意圖的簡報：

工作流程：
1. 將概念建立為 .md 中的 Mermaid（此技能——第一階段）
2. 將相同概念描述給 scientific-schematics 以產生精美的 PNG（第三階段）
3. 兩者都提交——.md 作為來源，PNG 作為輔助圖表

與 scientific-writing 搭配

當 scientific-writing 產生手稿時，所有圖表和結構圖都應使用此技能的標準。寫作技能負責散文和引用；此技能負責視覺結構。

工作流程：
1. 使用 scientific-writing 起草手稿
2. 對於每個顯示工作流程、架構或關係的圖表：
   - 用遵循此技能指南的 Mermaid 圖表取代佔位符
3. 僅對真正需要寫實/複雜渲染的圖表使用 scientific-schematics

與 literature-review 搭配

文獻回顧會產生帶有大量關係資料的摘要。使用此技能來：

  • 建立文獻領域的概念圖（Mindmap）
  • 顯示出版時間軸（Timeline 或 Gantt）
  • 比較方法論（Quadrant 或 Radar）
  • 圖示論文中描述的資料流（Sequence 或 Flowchart）

與任何產生輸出文件的技能搭配

在完成任何技能的文件前，套用此技能的檢查清單：

  • [ ] 文件是否使用範本？如果是，我是否從正確的範本開始？
  • [ ] 所有圖表是否都是 Mermaid 並帶有 accTitle + accDescr？
  • [ ] 是否沒有 %%{init}、沒有內聯 style，僅有 classDef？
  • [ ] 所有外部主張是否都以 [^N] 引用？
  • [ ] 是否只有一個 H1，表情符號僅在 H2？
  • [ ] 每個 </details> 後是否有水平線？

📚 參考索引

樣式指南

指南 路徑 行數 涵蓋內容
Markdown 樣式指南 references/markdown_style_guide.md ~733 標題、格式、引用、表格、Mermaid 整合、範本、品質檢查清單
Mermaid 樣式指南 references/mermaid_style_guide.md ~458 無障礙、表情符號集、顏色類別、主題中立性、類型選擇、複雜度分級

圖表類型指南（24 種類型）

每個檔案包含：生產品質範例、該類型專屬提示，以及可複製貼上的範本。

references/diagrams/ — architecture, block, c4, class, complex_examples, er, flowchart, gantt, git_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user_journey, xy_chart, zenuml

文件範本（9 種類型）

templates/ — decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report

範例

assets/examples/example-research-report.md — 一份完整的科學研究報告，示範正確的標題階層、多種圖表類型（flowchart、sequence、gantt）、表格、註腳引用、可折疊章節，以及所有樣式指南規則的應用。

📝 出處

此技能中的所有樣式指南、圖表類型指南和文件範本皆移植自 SuperiorByteWorks-LLC/agent-project 儲存庫，採用 Apache-2.0 授權。

此技能（作為 scientific-agent-skills 的一部分）以 MIT 授權發布。所包含的 Apache-2.0 內容相容於下游使用，並保留出處，如本技能各檔案標頭所示。

[^1]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

[^2]: Mermaid. "Mermaid Diagramming and Charting Tool." https://mermaid.js.org/