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 License のもとで SuperiorByteWorks-LLC/agent-project リポジトリから移植したものです。

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

このスキル（research-agent-skills の一部）は MIT License のもとで配布されています。含まれる Apache-2.0 のコンテンツは、スキル全体のファイルヘッダーに保持されている帰属表示を残すことで、下流での利用にも適合します。

---

エージェントの作業手順

1. 環境を確認します。 作業に取りかかる前に、ユーザーの草稿、データ、図、投稿先を収集します。
2. 入力を確定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果を左右する値を推測せず、質問します。
3. まず小規模に実行します。 1つのセクションまたは段落を作成し、文調、構成、用語についてユーザーの確認を得ます。
4. 上記の指示と参考資料に従って、タスク全体を実行します。
5. 結果を検証します。 すべての主張がユーザーのデータまたは検証済みの情報源に基づいていること、数値が表や図と一致していること、引用が実在することを確認します（citation-verification）。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

次の事態が発生した場合	対応
主張に裏付けとなるデータや引用がない	裏付けを捏造するのではなく、本文で [citation needed] などと明示します。
これらの指示にある関数、フラグ、エンドポイントがインストール済みのバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適切に対応してユーザーに伝えます。API を決して捏造しません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しません。実行または検証できない場合は、その旨を明確に伝えます。
• ユーザーが著者です。ユーザーが提示または承認していない結果、参考文献、主張を追加しません。
• ここにあるバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有 GPU やクラウドの利用枠を消費する、個人情報や患者データに触れる、または取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• literature-review: PubMed、arXiv、bioRxiv、Semantic Scholar（および parallel-cli によるウェブ検索）を検索して、システマティックな文献レビューを実施し、スクリーニングします…
• academic-plotting: 研究内容に基づき、ML 論文向けの出版品質の図を作成します。