markdown-mermaid-writing

Markdown 與 Mermaid 撰寫

概述

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

核心信念：在 .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 diff 可讀	✅	❌ 二進位 Blob
可編輯，無需重新生成	✅	❌
相較於散文，Token 效率更高	✅ 更小	❌ 更大
無需建置步驟即可渲染	✅	❌ 需要託管
AI 無需視覺即可解析	✅	❌
可在 GitHub / GitLab / Notion 使用	✅	⚠️ 若需託管
無障礙（螢幕閱讀器）	✅ accTitle/accDescr	⚠️ 需要替代文字
之後可轉換為圖片	✅ 隨時	— 已是圖片

三階段工作流程

flowchart LR
    accTitle: 三階段文件工作流程
    accDescr: 第一階段：Markdown 中的 Mermaid 是必備且為唯一真相來源。第二和第三階段是選擇性的下游轉換，用於產出精美的最終成果。

    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 種圖表類型。幾乎所有科學關係都能找到對應：

使用案例	圖表類型	檔案
實驗工作流程 / 決策邏輯	流程圖	references/diagrams/flowchart.md
服務互動 / API 呼叫 / 訊息傳遞	時序圖	references/diagrams/sequence.md
資料模型 / Schema	ER 圖	references/diagrams/er.md
狀態機 / 生命週期	狀態圖	references/diagrams/state.md
專案時間軸 / 路線圖	甘特圖	references/diagrams/gantt.md
比例 / 組成	圓餅圖	references/diagrams/pie.md
系統架構（縮放層級）	C4 圖	references/diagrams/c4.md
概念層級 / 腦力激盪	心智圖	references/diagrams/mindmap.md
按時間順序的事件 / 歷史	時間軸	references/diagrams/timeline.md
類別層級 / 類型關係	類別圖	references/diagrams/class.md
使用者旅程 / 滿意度圖	使用者旅程圖	references/diagrams/user_journey.md
雙軸比較 / 優先級排序	象限圖	references/diagrams/quadrant.md
需求追溯性	需求圖	references/diagrams/requirement.md
流量規模 / 資源分佈	桑基圖	references/diagrams/sankey.md
數值趨勢 / 長條圖與折線圖	XY 圖表	references/diagrams/xy_chart.md
元件佈局 / 空間安排	區塊圖	references/diagrams/block.md
工作項目狀態 / 任務欄位	Kanban 圖	references/diagrams/kanban.md
雲端基礎設施 / 服務拓撲	架構圖	references/diagrams/architecture.md
多維度比較 / 技能雷達圖	雷達圖	references/diagrams/radar.md
階層式比例 / 預算	矩形樹狀圖	references/diagrams/treemap.md
二進位協定 / 資料格式	封包圖	references/diagrams/packet.md
Git 分支 / 合併策略	Git 圖	references/diagrams/git_graph.md
程式碼風格時序（程式語法）	ZenUML	references/diagrams/zenuml.md
多圖表組合模式	複雜範例	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 標題使用 Emoji — 每個 H2 一個 Emoji，H3/H4 中不使用
• 引用一切 — 每個外部主張都需加上註腳 [^N] 並附上完整 URL
• 謹慎使用粗體 — 每個段落最多 2-3 個粗體詞，絕不用於完整句子
• 每個 </details> 後加上水平線 — 強制規定
• 比較、配置、結構化資料使用表格而非散文
• 使用圖表取代文字牆 — 若描述流程、結構或關係，請加上 Mermaid

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

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

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

每個圖表的強制規則：

accTitle: 簡短名稱 3-8 個字
accDescr: 一兩句話解釋此圖表顯示的內容。

• 無 %%{init} 指令 — 會破壞 GitHub 深色模式
• 無內聯 style — 僅使用 classDef
• 每個節點最多一個 Emoji — 放在標籤開頭
• 使用 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 圖表 vs 雷達圖混淆

圖表	關鍵字	軸語法	資料語法
XY 圖表（長條圖/折線圖）	xychart-beta	x-axis ["Label1", "Label2"]	bar [10, 20] 或 line [10, 20]
雷達圖（蜘蛛網圖）	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

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

• 建立文獻領域的概念圖（心智圖）
• 顯示發表時間軸（時間軸或甘特圖）
• 比較方法論（象限圖或雷達圖）
• 繪製論文中描述的資料流程（時序圖或流程圖）

搭配任何產出文件的技能

在最終確定任何技能產出的文件之前，套用此技能的檢查清單：

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

---

📚 參考索引

樣式指南

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

圖表類型指南（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 — 一份完整的研究報告，示範了正確的標題層級、多種圖表類型（流程圖、時序圖、甘特圖）、表格、註腳引用、可摺疊章節以及所有樣式指南規則的應用。

---

📝 出處

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

• 來源：https://github.com/SuperiorByteWorks-LLC/agent-project
• 作者：Clayton Young / Superior Byte Works, LLC (@borealBytes)
• 授權：Apache-2.0

此技能（作為 scientific-agent-skills 的一部分）根據 MIT 授權條款發布。包含的 Apache-2.0 內容與下游使用相容，需保留出處，如本技能各檔案標頭所維護。

---