Skill 意思決定フローチャート生成器
SKILL.mdを読み取り、構造化データnodes.jsonを抽出し、スクリプトが決定論的にフローチャートHTMLを生成します。
分担
| フェーズ | 担当 | 理由 |
|---|---|---|
| SKILL.md → nodes.json | AI | SKILL.mdは自然言語であり、セマンティクスが不安定なため、AIが文脈を理解する必要があります |
| nodes.json → HTML | スクリプト | 座標計算は決定論的で再現可能、かつピクセル単位で揃える必要があります |
AIは構造化データのみを出力し、絶対に座標やSVGを出力しません。スクリプトは幾何計算のみを行い、決してセマンティクスを推測しません。
実行手順
1. SKILL.mdを読み取る
ユーザーが指定したSKILL.mdを読み取ります。見つからない場合は、ユーザーにパスを入力するよう尋ねます。
2. AIがnodes.jsonを抽出
以下のスキーマに従ってJSONを出力します。各出力エッジには必ずsideフィールドを明示的に付与してください — これはAIのセマンティクス判断であり、スクリプトは推測しません。
トップレベル構造
{
"title": "スキル名",
"subtitle": "任意の説明",
"nodes": [ ... ],
"edges": [ ... ],
"loops": [ ... ],
"legend": [ ... ]
}
nodes:必須、ノード配列edges:必須、有向エッジ配列loops:オプション、ループ破線(後述)legend:通常は空[]にし、デフォルトの凡例を使用
ノード type
| type | 意味 | 形状 |
|---|---|---|
entry | フロー開始点 | 角丸矩形 |
decision | 決定点(はい/いいえ、あり/なし) | 菱形 |
process | 処理ステップ | 角丸矩形 |
output | レポート/ファイル出力 | 角丸矩形 |
terminal | 終了/エラー終了 | 角丸矩形 |
ノード role(配色)
| role | 意味 | fill / stroke |
|---|---|---|
ai | AI推論 / LLM呼び出し | #E6F1FB / #185FA5 |
output | レポート / ファイル出力 | #EEEDFE / #534AB7 |
decision | 決定点 | #FAEEDA / #854F0B |
script | スクリプト実行 | #E1F5EE / #0F6E56 |
terminal | 終了 / エラー | #FCEBEB / #A32D2D |
1つのノードは1つのroleのみ持てます。 あるステップが複数の異なる性質の作業(異なるroleに対応)を含む場合は、複数のノードに分割して直列に接続する必要があります。例えば「スクリプトでベースライン取得 + AIで補足分析」はrole=aiの1つのノードにまとめず、role=scriptとrole=aiの2つのノードに分割する必要があります。
エッジ side(重要!)
| side | 意味 | レイアウト動作 |
|---|---|---|
bottom | メインフローを下方向に | targetはfromの次の階層、cxはfromを継承 |
left | 決定左分岐 / 分岐左 | 決定→同じ階層で水平接続;通常→次の階層に直交折線 |
right | 決定右分岐 / 分岐右 | 同上、方向は逆 |
sideのセマンティクス判断はAIが行います:
- 決定菱形(type=decision)の
left/right→ 決定と同じ階層、水平線で接続 - 通常矩形(type=process/output)の
left/right→ 次の階層、直交折線(垂直→水平→垂直、斜線はなし)
loops(ループ、オプション、破線)
フローに「以前のステップに戻る」ロジックがある場合に使用します。例:
- 修正後に再レビュー(
apply_fix → entry) - 再試行(
retry → checkpoint) - 条件を満たすまでループ(
recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "修正後に再レビュー", "path": "left_edge" }
フィールド説明:
from:ループ開始ノードのid(通常は最後のステップ)to:ループ終了ノードのid(通常はフロー開始点またはチェックポイント)label:ループラベル、破線の横に表示path:固定で"left_edge"(図の左端に沿ってルーティング)
注意:
- ループの開始点から終了点までのエッジをedgesで重複して描画しないでください。重複レンダリングの原因になります
- loops内のfrom/toノードはdepth計算に参加しません
legend
通常は空[]にし、スクリプトがデフォルトの5色凡例を使用します。カスタマイズが必要な場合:
[
{ "label": "AI実行", "fill": "#E6F1FB", "stroke": "#185FA5" },
{ "label": "出力/レポート", "fill": "#EEEDFE", "stroke": "#534AB7" },
{ "label": "決定点", "fill": "#FAEEDA", "stroke": "#854F0B" },
{ "label": "スクリプト", "fill": "#E1F5EE", "stroke": "#0F6E56" },
{ "label": "終了", "fill": "#FCEBEB", "stroke": "#A32D2D" }
]
3. スクリプトを呼び出してHTMLを生成
python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html
スクリプトは以下を行います:
- idの一意性、side/type/roleの妥当性、from/to参照の妥当性を検証
- 階層を自動計算(決定側枝は同じ階層 / 通常分岐は下の階層 / 合流点 = max(入力エッジ)+1)
- x(sideが決定)とy(階層+ノード高さに基づく)を自動計算
- 接続線をレンダリング(水平側枝 / 直交折線 / 垂直メインフロー / 合流3セグメント / ループ破線)
- viewBoxと下部凡例を自動設定
- 自己完結型HTMLを出力
nodes.json サンプル
docs/halucatch-v2-nodes.json— 完全版サンプル(ループ、3分岐、合流点を含む)docs/halucatch-nodes.json— 基本サンプルdocs/security-review-nodes.json— 複数決定点サンプルdocs/self-nodes.json— 最小サンプル(9ノード)
自己チェックリスト
- 入口ノード type=entry が最上部にある
- 各エッジに side フィールドがある(bottom/left/right)
- 決定菱形の side=left/right は側枝(同じ階層、水平接続)
- 通常矩形の side=left/right は分岐(下の階層、直交折線)
- 1ノード1role、混合ステップは分割済み
- 合流点(複数の入力エッジが同じノードに集まる)は特別な処理不要。スクリプトが自動認識
- ループは loops フィールドを使用し、edges で重複しない
- 全ノード id が edges の from/to で参照されている(孤立ノードなし)
- 凡例は空
[]
よくある質問
Q: ノードが重なってしまいました。
sideフィールドが不足していないか確認してください。決定分岐には必ずside(left/right/bottom)が必要です。そうしないと、2つのターゲットノードが同じ位置を継承してしまいます。
Q: ループ破線が描画されません。
ループはloops配列で宣言します(edgesではありません)。また、from/toをedgesで重複して宣言しないでください。pathは固定で"left_edge"です。
Q: スクリプトがJSONフォーマットエラーを報告します。 JSONはコメントやシングルクォートをサポートしていません。よくある問題:カンマ不足、余分なカンマ(配列末尾)、シングルクォート。
詳細はdocs/FAQ.mdを参照してください。