alterlab-mermaid

Markdown と Mermaid による執筆

概要

このスキルは、埋め込み Mermaid 図を標準かつ正式な形式として使用し、Markdown で科学ドキュメントを作成する方法を教え、その標準を徹底します。

基本的な考え方は、.md ファイル内の Mermaid 図で表現した関係は、どんな画像よりも価値があるということです。テキストなので、git で差分を明確に確認できます。ビルド手順は不要です。GitHub、GitLab、Notion、VS Code、その他あらゆる Markdown ビューアーでネイティブに表示できます。同じ関係を文章で説明するよりもトークン数が少なくて済みます。また、いつでも洗練された画像に変換できますが、テキスト版が常に信頼できる唯一の情報源であり続けます。

「レポートやファイルを、Mermaid も含めて通常のテキストとして .md 形式にするほど、Mermaid はシンプルな『スクリプト言語』でもあるため、後続のレンダリング、特に AI 生成画像の作成に役立ちます（関係を長文で説明するより、Mermaid を使うほうがトークン数を節約できます）。さらに、Mermaid は Markdown とともにレンダリングできるため、人間にも AI にも、ほとんどどこでも簡単に利用できます。」

— Clayton Young (@borealBytes)、2026-02-19

このスキルを使用する場面

次の場合にこのスキルを使用します。

• Markdown ドキュメント（README、使い方ガイド、意思決定記録、プロジェクトドキュメント、進捗レポート、分析レポート）を作成する場合
• 構造図や関係図（ワークフロー、データパイプライン、アーキテクチャ、タイムライン、スキーマ）を作成する場合
• バージョン管理する出力を作成する場合 — git に追加するものは Markdown にします
• ドキュメント内に「図を追加」したり「関係を可視化」したりするよう依頼された場合 — まず Mermaid を使用します

構造図や関係図の作成に Python matplotlib、seaborn、AI による画像生成を最初から使用しないでください。これらはフェーズ 2 とフェーズ 3 で使用します。Mermaid では必要な内容を表現できない場合（実データを使った散布図、フォトリアリスティックな画像など）に限り使用してください。テキスト図なら差分を確認でき、編集も可能なためです。

該当しないケース

シナリオ	代わりに使用するもの
原稿の文章（序論、方法、考察）を執筆または改訂する	alterlab-scientific-writing / alterlab-paper-writer
模式図やアーキテクチャの、AI でレンダリングした洗練された出版用図版（PNG）	alterlab-scientific-schematics
実際の数値データのプロット（散布図、分布図、ヒートマップ）	alterlab-matplotlib / alterlab-seaborn
PDF、Office ファイル、Web ページを Markdown に変換する	alterlab-markitdown

🎨 ソース形式に関する考え方

テキストベースの図が優れている理由

重要な点	Markdown 内の Mermaid	Python / AI 画像
git の差分を読み取れる	✅	❌ バイナリデータ
再生成せずに編集できる	✅	❌
文章と比べてトークン効率がよい	✅ 少ない	❌ 多い
ビルド手順なしで表示できる	✅	❌ ホスティングが必要
ビジョン機能なしで AI が解析できる	✅	❌
GitHub / GitLab / Notion で動作する	✅	⚠️ ホスティングされている場合
アクセシビリティ（スクリーンリーダー）	✅ accTitle/accDescr	⚠️ 代替テキストが必要
後から画像に変換できる	✅ いつでも	— すでに画像

3 フェーズのワークフロー

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

フェーズ 1 は必須です。 フェーズ 2 または 3 に進む場合も、Mermaid のソースは必ずコミットしてください。

Mermaidで表現できること

このスキルには、23種類のMermaid図と、複数の図を組み合わせるためのガイドがあります。科学的な関係のほとんどは、次のいずれかで表現できます。

用途	図の種類	ファイル
実験ワークフロー／意思決定ロジック	フローチャート	references/diagrams_flowchart.md
サービス間のやり取り／API呼び出し／メッセージング	シーケンス図	references/diagrams_sequence.md
データモデル／スキーマ	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
2軸比較／優先順位付け	クアドラント図	references/diagrams_quadrant.md
要件のトレーサビリティ	要件図	references/diagrams_requirement.md
フローの規模／リソースの分布	サンキー図	references/diagrams_sankey.md
数値の傾向／棒グラフ＋折れ線グラフ	XYチャート	references/diagrams_xy_chart.md
コンポーネントのレイアウト／空間配置	ブロック図	references/diagrams_block.md
作業項目のステータス／タスク列	カンバン	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

💡 簡単な種類ではなく、適切な種類を選びましょう。 何でもフローチャートにするのは避けてください。 時系列イベントにはフローチャートよりタイムラインが適しています。サービス間のやり取りにはフローチャートより シーケンス図が適しています。表を確認して、用途に合ったものを選びましょう。

レンダラーのバージョンは重要です。 GitHub、GitLab、Notion、VS Codeには、それぞれ独自のMermaidリリースがバンドルされています。Mermaid 12.0（2026年9月）では、フローチャート、クラス図、ER図、状態図、要件図がデフォルトでELKレイアウトに切り替わり、これらの図とシーケンス図のデフォルトテーマおよび外観がredux-color／neoになりました。そのため、同じソースでも、12.xのレンダラーでは11.xのものとはレイアウトや見た目が異なる場合があります。特定のレンダラー向けに間隔を細かく調整するのは避けてください。xychart、block、sankey、packetは、Mermaid 11.9～11.10で-betaの接尾辞がなくなりました。現在のMermaidではどちらの表記も解析できます。また、このスキルで使われている-beta形式も、古いレンダラーで動作します。新しい種類（例：venn-beta、ishikawa-beta、wardley-beta、swimlane、ユースケース、agentflow-beta）については、ここにガイドがありません。使用する前に、対象のレンダラーが対応していることを確認してください。

---

🔧 基本的なワークフロー

ステップ 1：ドキュメントの種類を特定する

一から書き始める前に、テンプレートがあるか確認します。

ドキュメントの種類	テンプレート
プルリクエストの記録	templates/pull_request.md
Issue／バグ／機能リクエスト	templates/issue.md
スプリント／プロジェクトボード	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 は 1 つ — タイトルです。それ以上は使用しません。
• 絵文字を使うのは H2 見出しのみ — H2 ごとに絵文字を 1 つ使い、H3/H4 では使用しません。
• すべてに出典を付ける — 外部情報を含む主張には、完全な URL を記載した脚注 [^N] を付けます。
• 太字は控えめに — 段落ごとに太字の語句は最大 2〜3 個とし、文全体を太字にしません。
• </details> の後には必ず水平線を入れる — 必須です。
• 比較、設定、構造化データには、文章より表を使う
• 長い文章より図を使う — フロー、構造、関係を説明する場合は、Mermaid を追加します。

ステップ 3：図の種類を選び、そのガイドを読む

Mermaid 図を作成する前に、references/mermaid_style_guide.md を読みます。

次に、該当する種類のファイル（例：references/diagrams_flowchart.md）を開き、サンプル、ヒント、コピーして使えるテンプレートを確認します。

すべての図で守る必須ルール：

accTitle: Short Name 3-8 Words
accDescr: One or two sentences explaining what this diagram shows.

• %%{init} ディレクティブは使わない — GitHub のダークモードで問題が発生します。
• インラインの style は使わない — classDef のみを使用します。
• ノードごとの絵文字は最大 1 つ — ラベルの先頭に置きます。
• ノード ID は snake_case にする — ラベルと一致させます。

ステップ 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 ではなく radar-beta を使用する（単独のキーワードは存在しません）。
• x-axis ではなく、axis を使って次元を定義する。
• コロン付きの引用ラベルではなく、curve を使ってデータ系列を定義する。
• accTitle/accDescr は使用できます — radar-beta の次の行に記述します（Mermaid 11.12、11.17、12.0 で確認済み）。

XY チャートとレーダーチャートの混同

図	キーワード	軸の構文	データの構文
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 は SVG のアクセシブルなタイトルと説明としてレンダリングされます。Mindmap、Sankey、Block の各図はこれらを記述すると解析に失敗します。Treemap は古いレンダラーでは失敗します（Mermaid 11.12 では確認済み。11.17 と 12.0 では受け入れられます）。Timeline と Kanban は受け入れますが、出力から削除されます（Mermaid 11.12、11.17、12.0 で確認済み）。この 6 種類では、代わりにコードブロックの直前に説明的な斜体の段落を配置します。

手法の系統ごとに分類した、文献の全体像を示すマインドマップです。マインドマップは accTitle/accDescr をサポートしていません。

mindmap
...

---

🔗 他のスキルとの連携

alterlab-scientific-schematics との連携

alterlab-scientific-schematics は、AI を活用して出版物向けの高品質な画像（PNG）を生成します。Mermaid 図を概略図のブリーフとして使用します。

Workflow:
1. Create the concept as Mermaid in .md (this skill — Phase 1)
2. Describe the same concept to alterlab-scientific-schematics for a polished PNG (Phase 3)
3. Commit both — the .md as source, the PNG as a supplementary figure

alterlab-scientific-writing との併用

alterlab-scientific-writing が原稿を作成する場合、すべての図と構成図には、このスキルの基準を適用してください。文章と引用はライティングスキルが担当し、視覚的な構成はこのスキルが担当します。

Workflow:
1. Use alterlab-scientific-writing to draft the manuscript
2. For every figure that shows a workflow, architecture, or relationship:
   - Replace placeholder with a Mermaid diagram following this skill's guide
3. Use alterlab-scientific-schematics only for figures that truly need photorealistic/complex rendering

alterlab-literature-review との併用

文献レビューでは、関連性に関するデータを多く含む要約を作成します。このスキルを使って、次の作業を行ってください。

• 文献の全体像を示す概念マップ（マインドマップ）を作成する
• 出版時期を示すタイムライン（タイムラインまたはガントチャート）を作成する
• 方法論を比較する（四象限図またはレーダーチャート）
• 論文で説明されているデータフローを図示する（シーケンス図またはフローチャート）

出力ドキュメントを作成するすべてのスキルとの併用

いずれかのスキルで作成したドキュメントを最終化する前に、このスキルのチェックリストを適用してください。

• ドキュメントでテンプレートを使用していますか？使用している場合、適切なテンプレートを使い始めましたか？
• すべての図が accTitle + accDescr を含む Mermaid で作成されていますか（これらを使用できない6種類については、斜体の説明が付いていますか）？
• %%{init} やインラインの style はなく、classDef のみを使用していますか？
• 外部の主張にはすべて [^N] で引用を付けていますか？
• H1 は1つだけで、絵文字は H2 のみに使われていますか？
• </details> の後に必ず水平線がありますか？

---

📚 リファレンスインデックス

スタイルガイド

ガイド	パス	行数	内容
Markdown スタイルガイド	references/markdown_style_guide.md	約733	見出し、書式設定、引用、表、Mermaid の統合、テンプレート、品質チェックリスト
Mermaid スタイルガイド	references/mermaid_style_guide.md	約458	アクセシビリティ、絵文字セット、色クラス、テーマの中立性、種類の選択、複雑さの段階

図の種類別ガイド（24種類）

各ファイルには、本番品質の例、その種類に特化したヒント、コピーして使えるテンプレートが含まれています。

references/diagrams_ — アーキテクチャ、ブロック、c4、クラス、複雑な例、er、フローチャート、ガント、git グラフ、カンバン、マインドマップ、パケット、円グラフ、四象限図、レーダーチャート、要件、サンキー、シーケンス、状態、タイムライン、ツリーマップ、ユーザージャーニー、xy チャート、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 — 適切な見出し階層、複数の図の種類（フローチャート、シーケンス図、ガントチャート）、表、脚注による引用、折りたたみ可能なセクションを示し、すべてのスタイルガイドの規則を適用した、完全な科学研究レポートです。

---

📝 帰属表示

このスキルに含まれるすべてのスタイルガイド、図の種類別ガイド、ドキュメントテンプレートは、Apache-2.0 ライセンスに基づき SuperiorByteWorks-LLC/agent-project リポジトリから移植されています。

• ソース：https://github.com/SuperiorByteWorks-LLC/agent-project
• 著者：Clayton Young / Superior Byte Works, LLC (@borealBytes)
• ライセンス：Apache-2.0

このスキルのライセンスは Apache-2.0（フロントマターの license）です。これは、その大部分のコンテンツが上記の Apache-2.0 ライセンスのソースから移植されているためです。一方、AlterLab Academic Skills リポジトリ全体のライセンスは MIT です（THIRD_PARTY_NOTICES.md を参照）。移植したファイルの帰属表示ヘッダーは残し、このスキルを単体で再配布する場合は Apache-2.0 ライセンスの本文を含めてください。ここで行った変更は、リポジトリの CHANGELOG に記録されています。

---