markdown-mermaid-writing

Markdown と Mermaid のライティング

概要

このスキルは、Mermaid の構造図を伴う Markdown ドキュメント向けの任意のハウススタイルを提供します。まず、要求された出力形式、既存のリポジトリの規約、ジャーナルの要件に従ってください。このスキルは科学分析やプロットを代替するものではありません。

.md ファイル内で Mermaid として表現された関係は、編集可能なテキストであり、git でクリーンに差分表示されます。互換性のあるホストは、ユーザー側での別途ビルド手順なしにそれをレンダリングします。ホストが Mermaid をサポートしている場所でレンダリングされますが、プレーンな Markdown ビューアではコードとしてしか表示されない場合があり、プラットフォームや拡張機能によって同梱される Mermaid のバージョンは異なります。コンパクトなソース表現を使用しますが、トークンの使用量は図によって異なります。SVG/PNG のエクスポートにはレンダラーが必要です。エクスポートした図と並べて図のソースを保持してください。

「レポートやファイルを .md で、ただの通常のテキストとして書けば書くほど、mermaid も同様にシンプルな『スクリプト言語』です。これは下流でのレンダリング、特に AI 生成画像にとって役立ちます（関係を説明するために長文テキストだけを使うのではなく mermaid を使うと < トークンになります）。さらに mermaid は markdown と一緒にレンダリングできるので、人間でも AI でもほとんどどこでも簡単に使えます。」

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

このスキルを使う場面

次の場合にこのスキルを使用してください：

• 要求された Markdown レポート、README、手法の概要、または研究ノートを書くとき
• ワークフロー、データパイプライン、スキーマ、状態機械、または概念的な関係を図示するとき
• 編集可能な Mermaid ソースと、そのレンダリング結果である SVG/PNG エクスポートを維持するとき

測定データ、不確かさ、統計グラフィックス、正確な幾何形状、または Mermaid が忠実に表現できない出版用図には、科学プロットツールを直接使用してください。Mermaid は、定量的なチャートや既存の SVG/コードネイティブなアセットの必須の前段階ではありません。

🎨 ソースフォーマットの哲学

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

重要な点	Markdown 内の Mermaid	Python / AI 画像
Git 差分が読みやすい	✅ テキストソース	プロットコード/SVG もテキストになり得る
編集可能なソース	✅	プロットスクリプトとベクターソースは編集可能
コンパクトな関係の記法	しばしば	表現方法による
ネイティブプレビュー	ホスト/バージョンによる	ビューア/形式による
ビジョンなしで AI が解析可能	✅	❌
送信先で動作する	Mermaid のサポートとバージョンを確認	画像形式のサポートを確認
アクセシブル（スクリーンリーダー）	SVG メタデータとテキスト代替を確認	alt テキスト/データテーブルを提供
後で画像に変換可能	✅ いつでも	— すでに画像

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

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Markdown holds the structural diagram source. Quantitative charts come from data and plotting code; optional illustrations require a separate factual review.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(structural source)"]
    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
    data["Data and plotting code"] --> 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

構造図には Mermaid を、定量的なチャートにはデータ/コードを保持してください。AI イラストは定量的な変換ではありません。すべてのラベルと関係をその情報源に対して検証してください。

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

💡 簡単なものではなく、適切な種類を選びましょう。 何でもかんでもフローチャートを既定にしないでください。 時系列の出来事にはフローチャートよりタイムラインが適しています。サービス間のやり取りには フローチャートよりシーケンスが適しています。表を見て照合してください。

---

🔧 コアワークフロー

ステップ 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: スタイルガイドを読む

この Markdown ワークフローでは、references/markdown_style_guide.md を読みます。絵文字、 見出しの数、水平線は、Markdown の構文要件ではなくハウススタイルとして扱います。

内部化すべき主要なルール:

• 1 ドキュメントにつき 1 つの H1 — タイトルです。それ以上は決して付けません。
• 絵文字は H2 見出しのみ — H2 に 1 つ、H3/H4 には付けません
• 事実に基づく主張を裏付ける — 検証済みの情報源と要求された引用形式を使用します
• 太字は控えめに — 段落ごとに最大 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} ディレクティブは非推奨であり、YAML 構成が推奨されます
• サポートされている場合は再利用可能な classDef を優先します。スタイル構文は図ごとに異なります
• 1 ノードにつき絵文字は最大 1 つ — ラベルの先頭に配置します
• 種類の構文に沿った説明的な ID を使用します: snake_case はフローチャートで機能しますが、ER/クラス/状態の規則は異なります

ステップ 4: ドキュメントを作成する

テンプレートから始めます。Markdown スタイルガイドを適用します。図は関連するテキストの インラインに配置します — 別個の「図」セクションには置きません。

納品前に実際の配信先でレンダリングします。新しい図の種類を選ぶ前に、その Mermaid バージョンとプラグイン要件を確認します。GitHub はこの確認用の info 図を文書化しています。 最新バージョンでのローカルプレビューが成功したからといって、GitHub やその他の ホストがレンダリングするとは限りません。Mermaid がサポートされていない場合は、 保持した .md ソースと併せて、テキストによる説明を付けたレンダリング済み SVG/PNG を提供します。

ステップ 5: ソースと検証の保持

.md ソース、レンダリング済みの成果物、テスト済みのレンダラーバージョンをまとめて 保持します。プロジェクトのバージョン管理ワークフローに従います。このスキル自体は コミットや公開を承認するものではありません。 CLI エクスポート、埋め込み、テスト済みのアクセシビリティマトリクスについては、 現在のレンダリングと検証を読みます。

---

⚠️ よくある落とし穴

レーダーチャートの構文 (radar-beta)

誤り (ドキュメントのレンダラーを壊さないようテキストとして表示):

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

正しい:

radar-beta
accTitle: Example Radar Scores
accDescr: Illustrative values of one, two, and three on a shared zero-to-three scale.
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3

• radar-beta を使用する (裸のキーワード radar は存在しません)
• 次元を定義するには axis を使用する (x-axis ではありません)
• データ系列を定義するには curve を使用する (コロン付きの引用ラベルではありません)
• Mermaid 12.0.0 の radar は accTitle/accDescr を出力します。古いホストを確認し、可視の説明を保持します

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

明示された共通のスコアスケールで 3 つの手法を比較するレーダーチャート。正確な値についてはデータ表を参照してください。

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 との併用

Mermaid の構造図を使用する原稿では、このスキルがダイアグラム構文を扱います。 原稿で求められる図の形式と、科学的可視化の慣例に従ってください。

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 plotting or schematic tools where appropriate to the scientific content

literature-review との併用

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

• 文献の全体像を概念マップ（Mindmap）として作成する
• 出版のタイムライン（Timeline または Gantt）を表示する
• 方法論を比較する（Quadrant または Radar）
• 論文で説明されているデータフローを図示する（Sequence または Flowchart）

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

このスキルを使用してドキュメントを完成させる前に、次を確認してください。

• ドキュメントはテンプレートを使用していますか？ 使用している場合、適切なテンプレートから始めましたか？
• 各ダイアグラムは適切な形式で、機能するアクセシビリティメタデータまたはテキストによる代替が付いていますか？
• 設定は出力先でサポートされており、ライト/ダークテーマでテストされていますか？
• 引用は外部の主張を裏付けており、合成値にはラベルが付いていますか？
• H1 は 1 つだけで、絵文字は H2 のみに付いていますか？
• 最終的な Markdown/HTML 構造は正しくレンダリングされますか？

---

📚 リファレンス索引

スタイルガイド

ガイド	パス	行数	内容
Markdown スタイルガイド	references/markdown_style_guide.md	ファイル参照	見出し、書式設定、引用、テーブル、Mermaid 統合、テンプレート、品質チェックリスト
Mermaid スタイルガイド	references/mermaid_style_guide.md	ファイル参照	アクセシビリティ、絵文字セット、カラークラス、テーマ中立性、型の選択、複雑度ティア
現在のレンダリング	references/current-rendering.md	ファイル参照	Mermaid 12 の変更点、CLI エクスポート、ブラウザー API、テスト済みアクセシビリティマトリクス、科学的チェック

ダイアグラムガイド（23 種類＋構成）

各ファイルには、本番品質の模範例、その種類に固有のヒント、コピー＆ペースト可能なテンプレートが含まれています。

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 — 明示的に創作されたデータ、監査可能な集計テーブル、構造的なフローチャート、棒グラフ、年表を含む合成の品質管理レポートです。実験やソフトウェア API に関する主張は一切含まれていません。

---

📝 帰属

このスキル内のすべてのスタイルガイド、ダイアグラム種類別ガイド、ドキュメントテンプレートは、Apache-2.0 ライセンスの下で SuperiorByteWorks-LLC/agent-project リポジトリから移植されたものです。

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

このスキル（scientific-agent-skills の一部として）は、MIT ライセンスの下で配布されています。含まれる Apache-2.0 コンテンツは、このスキル全体のファイルヘッダーに保持されているとおり、帰属を保持したまま下流で使用することが互換性をもって認められています。

---