MarkdownとMermaidライティング
概要
このスキルは、Markdownに埋め込まれたMermaid図表をデフォルトかつ正規の形式として使用する科学的なドキュメント作成の標準を教え、強制します。
核となる考え方:** .md ファイル内のMermaid図表として表現された関係は、画像よりもはるかに価値があります。テキストなのでGitでクリーンに差分を確認でき、ビルドステップは不要で、GitHub、GitLab、Notion、VS Code、その他あらゆるMarkdownビューアでネイティブにレンダリングされます。同じ関係を散文で説明するよりトークンが少なくて済み、後でいつでも洗練された画像に変換できます。そして、テキストバージョンは常にソースオブトゥルースとして残ります。
「レポートやファイルを.mdの通常のテキスト、つまりMermaidもシンプルな‘スクリプト言語’として使うほど、下流のレンダリング、特にAI生成画像において役立ちます（Mermaidは関係を説明する長文テキストよりもトークンが少なくて済みます）。さらにMermaidはMarkdownと一緒にレンダリングできるため、人間やAIがほぼどこでも簡単に使用できます。」
— Clayton Young (@borealBytes)、K-Dense Discord、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: 3フェーズのドキュメントワークフロー
accDescr: フェーズ1のMarkdown内Mermaidは常に必須であり、ソースオブトゥルースです。フェーズ2と3は、洗練された出力のためのオプションの下流変換です。
p1["📄 フェーズ1<br/>Markdown内のMermaid<br/>（常に — ソースオブトゥルース）"]
p2["🐍 フェーズ2<br/>Python生成<br/>（オプション — データチャート）"]
p3["🎨 フェーズ3<br/>AI生成ビジュアル<br/>（オプション — 仕上げ）"]
out["📊 最終成果物"]
p1 --> out
p1 -.->|"必要な場合"| p2
p1 -.->|"必要な場合"| 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: 短い名前 3〜8語
accDescr: この図表が何を示すかを説明する1〜2文。
%%{init}ディレクティブなし — GitHubのダークモードで壊れるため- インライン
styleなし —classDefのみ使用 - ノードあたり絵文字は最大1つ — ラベルの先頭に配置
- ノードIDは
snake_case— ラベルと一致させる
ステップ4: ドキュメントを書く
テンプレートから始めて、Markdownスタイルガイドを適用し、図表を別の「図」セクションではなく、関連するテキストとインラインに配置します。
ステップ5: テキストとしてコミットする
埋め込まれたMermaidを含む .md ファイルがコミットされるものです。PNGやAI画像も生成した場合、それらは補足であり、Markdownがソースです。
⚠️ よくある落とし穴
レーダーチャート構文 (radar-beta)
間違い:
radar
title 例
x-axis ["A", "B", "C"]
"シリーズ" : [1, 2, 3]
正解:
radar-beta
title 例
axis a["A"], b["B"], c["C"]
curve series["シリーズ"]{1, 2, 3}
max 3
radar-betaを使用し、radarは使わない（裸のキーワードは存在しない）- 次元を定義するには
axisを使用し、x-axisは使わない - データ系列を定義するには
curveを使用し、コロン付きの引用ラベルは使わない accTitle/accDescrなし — radar-betaはアクセシビリティアノテーションをサポートしていません。図表の上には常に説明的なイタリック体の段落を追加すること
XYチャートとレーダー chartの混同
| 図表 | キーワード | 軸構文 | データ構文 |
|---|---|---|---|
| XYチャート（棒/線） | xychart-beta | x-axis ["ラベル1", "ラベル2"] | bar [10, 20] または line [10, 20] |
| レーダー（蜘蛛/網） | radar-beta | axis id["ラベル"] | curve id["ラベル"]{10, 20} |
サポートされているタイプで accTitle/accDescr を忘れる
accTitle/accDescr をサポートしている図表タイプは一部のみです。サポートしていないタイプの場合は、コードブロックの直上に説明的なイタリック体の段落を常に配置してください：
5つのパフォーマンス次元にわたって3つの方法を比較するレーダーチャート。注：レーダーチャートはaccTitle/accDescrをサポートしていません。
radar-beta
...
🔗 他のスキルとの統合
scientific-schematics との連携
scientific-schematics はAI駆動の出版品質画像（PNG）を生成します。Mermaid図表を図のブリーフとして使用します：
ワークフロー:
1. 概念をMermaidで.mdファイルに作成（このスキル — フェーズ1）
2. 同じ概念をscientific-schematicsに説明し、洗練されたPNGを生成（フェーズ3）
3. 両方をコミット — .mdをソースとして、PNGを補足図として
scientific-writing との連携
scientific-writing が原稿を作成する場合、すべての図と構造図はこのスキルの標準を使用する必要があります。ライティングスキルは散文と引用を処理し、このスキルは視覚構造を処理します。
ワークフロー:
1. scientific-writingを使用して原稿を起草する
2. ワークフロー、アーキテクチャ、または関係を示すすべての図について:
- プレースホルダーをこのスキルのガイドに従ったMermaid図表に置き換える
3. 本当にフォトリアリスティック/複雑なレンダリングが必要な図にのみscientific-schematicsを使用する
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 — 適切な見出し階層、複数の図表タイプ（フローチャート、シーケンス図、ガントチャート）、テーブル、脚注引用、折りたたみ可能セクション、およびすべてのスタイルガイドルールが適用された完全な科学研究レポート。
📝 帰属
このスキルのすべてのスタイルガイド、図表タイプガイド、およびドキュメントテンプレートは、SuperiorByteWorks-LLC/agent-project リポジトリから Apache-2.0 ライセンスの下で移植されました。
- ソース: https://github.com/SuperiorByteWorks-LLC/agent-project
- 著者: Clayton Young / Superior Byte Works, LLC (@borealBytes)
- ライセンス: Apache-2.0
このスキル（scientific-agent-skills の一部として）は MIT ライセンスの下で配布されています。含まれる Apache-2.0 コンテンツは、このスキル全体のファイルヘッダーに保持されている帰属を伴い、下流での使用に互換性があります。