はじめに
AIエージェント（AntiGravity、Codexなど）に複雑なタスクを実行させる「スキル指示書（SKILL.md）」を書いていくと、ある問題にぶつかります。
テキストだけだと、処理の全体像が分かりにくい。
とくに「条件分岐」や「フェーズ間の依存関係」が増えてくると、
- 書いた本人も数日後に読み返すと混乱する
- AIが指示書を読み違えていても、ぱっと見では気づけない
という状況に陥ります。
今回は、SKILL.md にMermaid記法のフローチャートを並記することで「本文の指示」と「図解のフロー」が互いにチェックし合う体制を構築した話を書きます。
課題：テキスト指示書だけでは限界がある
私が実際に運用しているスキル create_articles を例にします。
このスキルは、
- Obsidianの
daily_log/フォルダからログを読み込む - 過去記事を参照して文体を分析する
- 投稿カレンダーに沿って記事を生成する
- プラットフォーム別フォルダへ自動保存する
という処理を行います。
テキストの指示書だけで書くと、こうなります。
### Phase 1: ログ読み込みと計画
1. daily_log/ フォルダから直近1週間分のファイルを読み込む
2. 投稿カレンダーに基づき、各曜日のタイトルとトピックを決定する
3. 執筆前に「文体チューニング」を行う
4. 執筆を開始する前に、全タイトル案をユーザーに報告する
### Phase 2: 執筆と保存（Loop処理）
- Day 0 (日): 週レポート → Note形式
- Day 1 (月): 技術・方法論 → Note形式
- Day 2 (火): 開発ログ → Note形式 ／ Qiita形式
- Day 3 (水): 技術・方法論 → Note形式
- Day 4 (木): 開発ログ → Note形式 ／ Qiita形式
...
読めなくはないですが、**「Phase 1 と Phase 2 はどこでつながっているのか」「Qiitaが出るのは火曜と木曜のどちらか？両方？」**が直感的に見えません。
解決：Mermaid記法でフローチャートを並記する
同じ指示書に、Mermaid記法でフローチャートを追加します。
```mermaid
flowchart TD
A["Phase 1: ログ読み込み"] --> B["daily_log/ から1週間分を特定"]
B --> C["投稿カレンダーを作成"]
C --> D["文体チューニング（過去5件分析）"]
D --> E{"ユーザーに報告"}
E -->|承認| F["Phase 2: 執筆ループ"]
F --> G["Day 0: 週レポート → Note"]
G --> H["Day 1: 技術 → Note"]
H --> I["Day 2: 開発 → Note"]
I --> J{"技術的に深い内容？"}
J -->|Yes| K["Qiita記事も追加生成"]
J -->|No| L["Day 3 へ進む"]
K --> L
L --> M["Day 3: 技術 → Note"]
M --> N["前半完了 → ユーザーに通知"]
```
こう書くことで、
- 「条件分岐が Day 2（火）と Day 4（木）にある」 ことが図から一目で分かる
- テキスト側に書き忘れた分岐がないか を図と突き合わせて確認できる
- AIエージェント側も Mermaid記法を解釈できるため、フローチャートの情報も踏まえて実行判断ができる
メリット：ダブルチェックとしてのMermaid
この手法の最大のメリットは、「テキスト」と「図」が独立した情報源になることです。
チェック方向1：テキスト → 図
テキストで「Qiitaは火曜と木曜に出すことがある」と書いているのに、図に条件分岐がなければ記載漏れに気づけます。
チェック方向2：図 → テキスト
図に「ユーザーへの報告」ノードがあるのに、テキスト側の手順に「報告する」が書かれていなければ指示の抜けが見つかります。
チェック方向3：AI → 両方
AIエージェントは、テキストとMermaidの両方を読み込んで実行します。どちらか片方に矛盾があれば、AIの挙動がおかしくなるので、テスト実行がそのまま品質チェックになります。
注意点：ダイバージェンスのリスク
テキストと図を両方メンテナンスするということは、片方だけ更新してもう片方を更新し忘れるリスクが生まれます。
対策として、
- テキストを修正したら、必ずMermaid図も更新する（ルールとして明文化）
- Mermaid図はNapkin AI等の最終成果物用ではなく、あくまで「AIが読める形式のチェックシート」として位置づける
最終的な図解が必要な場合は、MermaidではなくNapkin AI等の専用ツールで仕上げるのがおすすめです。
これは用途の切り分けの問題で、
- Mermaid → テキストベース・AIが読める・バージョン管理しやすい（＝チェック用）
- Napkin AI → ビジュアル重視・人間が見やすい（＝発表・共有用）
と使い分けています。
テンプレート：SKILL.md にMermaid図を追加する最小パターン
実際にスキル指示書にMermaid図を追加する最小のテンプレートを示します。
# スキル名：○○○
## 概要（テキスト）
このスキルは、XXXを読み込み、YYYを生成し、ZZZに保存します。
## フロー図（Mermaid）
```mermaid
flowchart TD
A["入力：XXXを読み込む"] --> B["処理：YYYを生成"]
B --> C{"判定：条件を満たす？"}
C -->|Yes| D["出力A：ZZZに保存"]
C -->|No| E["出力B：代替処理"]
```
## 詳細手順（テキスト）
### Phase 1
1. XXXフォルダから対象ファイルを読み込む
...
ポイントは、**概要（テキスト） → フロー図（Mermaid） → 詳細手順（テキスト）**の順に並べることです。
AIエージェントは上から順に読むため、最初にフロー図で全体像を把握した上で詳細手順に入る──という流れが、人間にもAIにも分かりやすく機能します。
まとめ
- AIスキル指示書（SKILL.md）にMermaid記法のフローチャートを並記することで、テキストと図解の相互チェック体制を構築できる
- 条件分岐や依存関係が増えてきたスキルほど、この方法の効果が大きい
- ただし、テキストと図の**ダイバージェンス（乖離）**が起きないよう、更新ルールの明文化が必要
- 最終的な発表用図解はNapkin AI等に任せ、MermaidはAIが読めるチェックシートとして使い分ける