markdown-mermaid-writing

Markdown と Mermaid の作成

概要

このスキルでは、科学的なドキュメントを作成する際の標準を定め、その標準に沿って作成する方法を説明します。デフォルトかつ正式な形式は、Mermaid の図を埋め込んだ Markdown です。

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

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

— Clayton Young (@borealBytes)、コミュニティでの議論、2026-02-19

このスキルを使う場面

次のような場合に、このスキルを使ってください。

• あらゆる科学的ドキュメントを作成するとき — レポート、分析、論文、方法のセクション
• あらゆるドキュメントを作成するとき — README、ハウツー、意思決定記録、プロジェクトドキュメント
• あらゆる図を作成するとき — ワークフロー、データパイプライン、アーキテクチャ、タイムライン、関係性
• バージョン管理する出力を作成するとき — git に入れるものはすべて Markdown にするべきです
• ほかのあらゆるスキルと連携するとき — このスキルは、ほかのすべての出力を取り巻くドキュメント層を定義します
• 「図を追加して」や「関係性を可視化して」と依頼されたとき — まずは必ず Mermaid を使ってください

構造図や関係図を作成する際に、Python の matplotlib、seaborn、または AI による画像生成から始めないでください。 これらはフェーズ 2 とフェーズ 3 であり、Mermaid では必要なものを表現できない場合にのみ使用します（例：実データを使った散布図、フォトリアリスティックな画像）。

🎨 ソース形式の考え方

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

重要な点	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 で表現できること

Mermaid は 24 種類の図に対応しています。科学的な関係のほとんどは、次のいずれかで表現できます。

ユースケース	図の種類	ファイル
実験のワークフロー／判断ロジック	フローチャート	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

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

---

🔧 基本的なワークフロー

ステップ 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 はアクセシビリティ注釈をサポートしていません。図の上に必ず説明的な斜体の段落を追加してください

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 をサポートする図の種類は一部だけです。サポートしていないものについては、コードブロックの直上に必ず説明的な斜体の段落を配置してください:

5 つのパフォーマンス次元にわたって 3 つの手法を比較するレーダーチャート。注: レーダーチャートは accTitle/accDescr をサポートしていません。

radar-beta
...

---

🔗 他のスキルとの統合

scientific-schematics との連携

scientific-schematics は AI を活用した出版品質の画像（PNG）を生成します。Mermaid 図を schematic のブリーフとして使用してください:

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

scientific-writing との連携

scientific-writing が原稿を生成するとき、すべての図や構造的な図表はこのスキルの標準に従うべきです。執筆スキルは文章と引用を扱い、このスキルは視覚的構造を扱います。

Workflow:
1. Use 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 scientific-schematics only for figures that truly need photorealistic/complex rendering

literature-review との連携

文献レビューは、多くの関係データを含む要約を生成します。このスキルを使用して:

• 文献の全体像のコンセプトマップ（マインドマップ）を作成する
• 出版タイムライン（タイムラインまたはガント）を示す
• 手法を比較する（クアドラントまたはレーダー）
• 論文で説明されているデータフローを図式化する（シーケンスまたはフローチャート）

出力ドキュメントを生成するあらゆるスキルとの連携

あらゆるスキルからのドキュメントを完成させる前に、このスキルのチェックリストを適用してください:

• ドキュメントはテンプレートを使用していますか? 使用している場合、正しいものから始めましたか?
• すべての図は accTitle + accDescr を備えた Mermaid ですか?
• %%{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/ — 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 — 見出し階層、複数の図の種類（フローチャート、シーケンス図、ガントチャート）、表、脚注形式の引用、折りたたみセクション、適用されるすべてのスタイルガイド規則を示した、完全な科学研究レポートです。

---

📝 クレジット

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

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

このスキルは、academic-skills の一部として MIT License の下で配布されています。含まれる Apache-2.0 ライセンスのコンテンツは、帰属表示を保持すれば、下流での利用と互換性があります。帰属表示は、このスキル全体のファイルヘッダーに維持されています。

---