/ 目錄 / 演練場 / mermaid-skill
● 社群 Agents365-ai ⚡ 即開即用

mermaid-skill

作者 Agents365-ai · Agents365-ai/mermaid-skill

在 Claude Code 中產生 Mermaid 圖表(.mmd),並透過 mmdc 轉譯為 PNG/SVG/PDF——支援 10 種以上圖表類型,自動排版。

一個處理完整 Mermaid 流程的 Claude Code 技能:撰寫 .mmd 原始碼、呼叫 mmdc 進行轉譯,並支援主要 Mermaid 類型(流程圖、時序圖、類別圖、狀態圖、ERD、甘特圖、git 圖、旅程圖、心智圖、C4)。不再需要貼到 Mermaid 線上編輯器。

為什麼要用

核心特性

即時演示

實際使用效果

mermaid-skill.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mermaid-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mermaid-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/Agents365-ai/mermaid-skill",
          "~/.claude/skills/mermaid-skill"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add mermaid-skill -- git clone https://github.com/Agents365-ai/mermaid-skill ~/.claude/skills/mermaid-skill

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: mermaid-skill

為目前專案繪製架構圖

👤 撰寫文件、ADR 或入門指南的開發者 ⏱ ~20 min beginner

何時使用: 你一直在 Slack 上解釋架構,想要一張示意圖。

前置條件
  • 已安裝 mmdc — npm i -g @mermaid-js/mermaid-cli
  • 已安裝 Skill — git clone https://github.com/Agents365-ai/mermaid-skill ~/.claude/skills/mermaid-skill
步驟
  1. 描述系統
    Use mermaid-skill. Draw a flowchart of our service: client → API gateway → (auth / orders / payments) → Postgres / Redis / Stripe.✓ 已複製
    → 包含有意義節點名稱的 .mmd 原始碼,已轉譯為 PNG 並存放至 docs/
  2. 補充細節
    Add labels on each edge showing the protocol (HTTPS, gRPC, TCP) and auth type.✓ 已複製
    → 更新後的原始碼並重新轉譯
  3. 提交
    Commit docs/architecture.mmd and its PNG.✓ 已複製
    → 執行 git add 與 commit

結果: 專案中有一份持續維護的圖表,而不是 Confluence 上過時的投影片。

注意事項
  • 圖表變成密密麻麻的線條迷宮 — 讓 Claude 使用子圖與方向提示;不要把所有東西塞在同一層
搭配使用: filesystem · git

除錯時產生時序圖

👤 追蹤跨服務錯誤的工程師 ⏱ ~15 min beginner

何時使用: 你試著理解一個非同步互動,但文字描述說不清楚。

步驟
  1. 描述流程
    Use mermaid-skill. Sequence diagram: browser → SSR → auth service → session store → page render, with failure mode when session is stale.✓ 已複製
    → 標注了失敗情境的時序圖
  2. 標記錯誤
    Highlight the line where the bug manifests.✓ 已複製
    → 在問題訊息上加上標注方塊/備註

結果: 一張可以貼到錯誤回報單的示意圖。

從實際資料庫結構產生 ERD

👤 資料工程師、後端開發者 ⏱ ~20 min intermediate

何時使用: 你需要在設計評審時展示資料庫結構的視覺化圖表。

步驟
  1. 擷取結構
    Use mermaid-skill. Read the schema.sql (or query the live DB via postgres MCP) and produce a Mermaid ERD.✓ 已複製
    → 包含關聯與基數的 .mmd ERD
  2. 簡化內容
    Drop audit tables and focus on the core domain entities.✓ 已複製
    → 精簡後的 ERD

結果: 無需手動繪製,即可得到準確的 ERD。

注意事項
  • 推斷出的基數有誤 — 請提供實際的外鍵定義,不要讓模型自行猜測
搭配使用: postgres

組合

與其他 MCP 搭配,撬動十倍槓桿

mermaid-skill + filesystem

將圖表與其描述的程式碼放在一起

For every service in services/, add a docs/architecture.mmd and render it.✓ 已複製
mermaid-skill + postgres

從線上資料庫自動產生 ERD

Connect to the staging DB and render its schema as a Mermaid ERD.✓ 已複製
mermaid-skill + git

圖表隨程式碼變更一同版本控制

Commit updated diagrams in the same PR as the code changes they describe.✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
write_mermaid description, diagram type 任何圖表繪製需求 0
render_mmdc .mmd path, output format 原始碼確認後執行轉譯 local mmdc
iterate_diagram current diagram + feedback 收到審閱者回饋時 0

成本與限制

運行它的成本

API 配額
None
每次呼叫 Token 數
極少——Mermaid 原始碼相當精簡
費用
免費(mmdc 為開源軟體)
提示
對於大型圖表,請分別產生子圖,以避免重試大範圍的重寫。

安全

權限、密鑰、影響範圍

憑證儲存:
資料出站: 技能本身不對外傳輸資料

故障排查

常見錯誤與修復

mmdc not found

全域安裝:npm i -g @mermaid-js/mermaid-cli

驗證: which mmdc
Render fails with syntax error

Mermaid 的語法因版本而異;執行 mmdc --version 並確認與技能預設版本相符

驗證: mmdc --version
Diagram is a mess of crossing edges

加入方向提示(TD/LR)、使用子圖分組,或拆分為多張圖表

替代方案

mermaid-skill 對比其他方案

替代方案何時用它替代權衡
PlantUML / draw.io需要更高的客製化程度或非 Mermaid 語法設定較繁瑣,使用不同的轉譯工具鏈
paperbanana-skill需要學術出版品質的圖表較重量級;適用於不同的美學目標

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills