ビジュアル — スキルグラフ可視化 は何をしますか？
プロジェクト内のすべてのスキルを有向グラフにマッピングします。各スキルが何を消費し、何を生成し、どのように連鎖してワークフローを形成するかを示します。出力は2種類 — 文書化用のMermaidマークダウンファイルと、探索用のインタラクティブブラウザグラフです。
開始時に告知: "スキルグラフをマッピング中..."
使用するタイミング
/visual を実行するのは以下のような場合です：
- すべてのスキルがどのように連携しているかをひと目で理解したいとき
- スキルエコシステムにコントリビューターを迎え入れるとき
- スキルの追加や変更後にグラフを監査したいとき
ワークフロー
ステップ 1: すべてのスキルをスキャン
find skills/ -name "SKILL.md" 2>/dev/null | sort
各SKILL.mdファイルを全文読み込みます。
ステップ 2: 各スキルからメタデータを抽出
各スキルファイルから、以下のフィールドを抽出します：
| フィールド | ソース |
|---|---|
id | ディレクトリ名 (例: skills/walkthrough/ → walkthrough) |
label | name フロントマター。既知の場合はREADMEの絵文字を前に付ける |
description | description フロントマター — 最初の文のみ |
triggers | 内容: テキスト内で見つかった /command パターン |
inputs | 内容: スキルが読み取るファイル/ソース (例: git diff, docs/plans/) |
outputs | 内容: スキルが書き込むファイル (例: .review/review.md) |
relationships | relationships フロントマター配列 — 下記スキーマ参照 |
リレーションシップ フロントマター スキーマ (明示的、推奨):
relationships:
- target: <skill-id> # 別のスキルのディレクトリ名
type: <relationship-type> # 以下のタイプのいずれか
label: <short phrase> # グラフエッジに表示されるラベル (5単語以内)
リレーションシップタイプ:
| タイプ | 意味 | 矢印スタイル |
|---|---|---|
leads-to | このスキルの後の推奨次のステップ | 実線 --> |
alternative | 同じ作業に対する別のアプローチ | 破線 -.-> |
complements | 異なる目的だが、一緒にうまく機能する | 実線 --> |
feeds-from | このスキルはターゲットの出力を消費する | 実線 --> |
analyzes | このスキルはターゲットのファイルを読み取り処理する | 実線 --> |
ステップ 3: 関係を推論する (フォールバックのみ)
relationships フロントマターがない スキルについては、内容から推論します：
- 名前付きトリガー参照: 別のスキルの
/commandまたはディレクトリ名に言及している場合 → そのスキルへのleads-toエッジ。 - 共有I/O: 2つのスキルが同じファイルパスを読み書きしている場合 → それらの間の
complementsエッジ。 - ワークフロー言語: 内容に「Xを実行した後」、「Yを使用する前に」、「Zとうまく機能する」が含まれる場合 → 表現に一致する有向エッジを作成。
- 知識シンクパターン: 他のスキルの出力を入力とせず、ナレッジストアにのみ書き込むスキル → 学習内容を保持することに言及する他のスキルから
leads-toエッジ。
推論されたエッジはすべてグラフモデル内で "inferred": true としてマークします。これらは両方の出力で破線としてレンダリングされます。
ステップ 4: 内部グラフモデルを構築
以下のJSON構造を内部で生成します (ディスクには書き込みません):
{
"skills": [
{
"id": "walkthrough",
"label": "🚶 walkthrough",
"description": "One sentence.",
"triggers": ["/walkthrough"],
"inputs": ["git diff"],
"outputs": []
}
],
"edges": [
{
"source": "walkthrough",
"target": "compound",
"type": "leads-to",
"label": "save session learnings",
"inferred": false
}
]
}
ステップ 5: docs/SKILL_GRAPH.md を書き込む
docs/ が存在しない場合は作成します。docs/SKILL_GRAPH.md を4つのセクションで書き込みます：
セクション 1 — 概要グラフ
## スキル概要
\`\`\`mermaid
flowchart LR
classDef skill fill:#1a1a2e,stroke:#4a90d9,color:#e0e0ff
classDef terminal fill:#0d2618,stroke:#4a9d6f,color:#a0ffa0
skill-a["絵文字 名前\n/トリガー"]:::skill
skill-b["絵文字 名前\n/トリガー"]:::skill
...
skill-a -->|"ラベル"| skill-b
skill-c -.->|"ラベル"| skill-d
\`\`\`
ルール:
leads-toおよびcomplementsエッジ: 実線-->alternativeおよび推論されたエッジ: 破線-.->- ノードラベル形式:
"絵文字 名前\n/トリガー"(改行には\nを使用) - 外向きの
leads-toエッジがないスキルは:::terminalクラスを取得 - MermaidノードIDは有効な識別子である必要があります — ハイフンをアンダースコアに置き換え、ラベルはそのままにします
セクション 2 — ワークフローチェーン
すべてのエントリポイントスキル (入力 leads-to エッジがないスキル) を見つけます。それぞれについて、完全な leads-to パスをトレースし、名前付きワークフローを書き込みます：
## ワークフロー
### コードレビューワークフロー
\`\`\`mermaid
flowchart LR
walkthrough -->|"学習内容を保存"| compound
\`\`\`
### 実装ワークフロー
...
\`\`\`
2つのパスが同じ終端ノードを共有する場合、1つの図に表示しても構いません。
セクション 3 — データフロー
入力ソース、スキル、出力成果物を表示します。メタデータに明示的な入力または出力があるスキルのみを含めます：
## データフロー
\`\`\`mermaid
flowchart LR
classDef artifact fill:#1a1a1a,stroke:#888,color:#ccc
classDef ext fill:#2a1a0a,stroke:#d9904a,color:#ffd0a0
git_diff["/"git diff"/"]:::ext
review_md["/".review/review.md"/"]:::artifact
git_diff --> review_diff
review_diff --> review_md
\`\`\`
セクション 4 — スキルインデックス
テーブル: スキル | トリガー | 説明 | 読み取り | 書き込み
ステップ 6: インタラクティブHTML出力を生成
ステップ4のグラフモデルを、1行にミニファイされたJSON文字列にシリアライズします。 このJSON文字列を以下の両方の出力で使用します (同じデータ、異なるテンプレート)。
6a — スキルダッシュボード (主要出力)
skills/visual/references/dashboard-template.html を開きます。
/* GRAPH_DATA_JSON */ をJSON文字列で置き換えます。
.docs/skill-dashboard.html に書き込みます。
ダッシュボードには3つのタブがあります:
- スキル — すべてのスキルのトリガー、説明、読み取り/書き込み、出力関係を含むカードグリッド
- グラフ — インタラクティブなCytoscapeグラフ (最初のタブが開かれたときに遅延初期化)
- ワークフロー — 自動導出されたワークフローチェーン、代替案、補完関係
6b — スタンドアロングラフ (二次出力)
skills/visual/references/graph-template.html を開きます。
/* GRAPH_DATA_JSON */ を同じJSON文字列で置き換えます。
.docs/skill-graph.html に書き込みます。
いずれかのテンプレートファイルが見つからない場合は、その出力をスキップし、レポートにその旨を記載します。
ステップ 7: 発見可能性チェック
CLAUDE.md で SKILL_GRAPH を検索します。見つからない場合、以下を提案します：
スキルグラフ
docs/SKILL_GRAPH.mdが CLAUDE.md でまだ参照されていません。 以下のブロックを追加すると、将来のエージェントが自動的に発見できるようになります。## スキルグラフ スキルの関係とワークフロー: `docs/SKILL_GRAPH.md` ダッシュボード (スキル+グラフ+ワークフロー): `.docs/skill-dashboard.html` スタンドアロングラフ: `.docs/skill-graph.html`CLAUDE.md に追加しますか? (はい/いいえ)
自動書き込みは行わないでください。 CLAUDE.md を修正する前に承認を待ちます。
ステップ 8: 完了レポートを出力
★ スキルグラフをマッピングしました
スキル数: N
関係数: M 明示的, K 推論
→ docs/SKILL_GRAPH.md [Mermaid概要 + ワークフロー + データフロー + インデックス]
→ .docs/skill-dashboard.html [ダッシュボード: スキルカード + グラフ + ワークフロー]
→ .docs/skill-graph.html [スタンドアロンインタラクティブグラフ]
CLAUDE.md: 参照あり ✓ / まだ参照されていません
主要な制約
- CLAUDE.md への自動書き込みは決して行わない — 常に最初に確認する
- 明示的優先 —
relationshipsフロントマターが常に優先され、推論されたエッジは両方の出力で破線になる - 冪等性 —
/visualを再実行すると両方の出力ファイルが完全に上書きされる - 非破壊的 — SKILL.md ファイルを一切変更しない。
docs/と.docs/にのみ書き込む - MermaidノードID: ハイフンをアンダースコアに置き換えてパースエラーを回避 (例:
review_diff、review-diffではない) - ノードラベル長: 読みやすさのため、
\nで分割された各行を20文字以内に抑える