skill-graph-audit

スキルグラフ監査

概要

マーケットプレイス全体における Skill(plugin:name) の呼び出しから有向グラフを構築し、構成パターンを明らかにします。具体的には、頻繁に参照されるスキル（ハブ）、多くのスキルをオーケストレーションするスキル（オーケストレーター）、入出力の参照がないスキル（孤立ノード）、存在しないスキルを参照するスキル（参照切れ）を特定します。

フェデレーショングラフを、手作業で整備せず、ソースから導出できるようになりました。

使用するタイミング

• スキル構成のドキュメントを更新する前
• 名前変更や廃止の後に、壊れた Skill() 参照を検出するとき
• 孤立したスキルを見つけるための四半期監査
• 統合候補を評価するとき（ハブは統合時のリスクが高くなります）
• 新しいスキルの外向き参照が妥当か確認するとき

使用しないタイミング

• スキルごとの品質評価には、代わりに Skill(abstract:skills-eval) を使用してください
• フロントマターや構造の検証には、Skill(abstract:plugin-review) を使用してください
• フック固有の監査には、Skill(abstract:hooks-eval) を使用してください

クイックスタート

# Positive control first. The fixture tree has a known answer (1
# bug-class dangling ref, 1 isolate, 2 edges); a regex that stopped
# matching would report plugins/ as clean, and this catches it.
uv run pytest -o addopts= -q plugins/abstract/tests/scripts/test_skill_graph.py -k Planted

python3 plugins/abstract/scripts/skill_graph.py \
  --plugins-root plugins --top-n 10

機械可読な出力を得るには：

python3 plugins/abstract/scripts/skill_graph.py \
  --plugins-root plugins --format json --output reports/skill-graph.json

CLI の全リファレンスとワークフロー例については、modules/usage.md を参照してください。

主な出力

出力	意味	数が多い場合の対応
ハブ	最も多く参照されるスキル	コア API として扱い、廃止には細心の注意を払う
オーケストレーター	多くのスキルを呼び出すスキル	各参照が引き続き解決されることを確認する
孤立ノード	入力も出力もゼロ	役割を確認する：ライブラリか、エントリーポイントか、誤記か
参照切れ：バグ	存在しない内部参照先	すぐに修正する（誤記または廃止されたスキル）
参照切れ：外部	外部プラグインへの参照	プラグイン依存関係を文書化する
参照切れ：プレースホルダー	-NAME のようなテンプレートテキスト	意図したものか確認する

誤検出に関するガイダンスと孤立ノードの分類については、modules/interpretation.md を参照してください。

実運用での検証結果

このスキル自体は TDD を最初に行う形で足場を構築しました。plugins/ に対する初回実行で、手動監査（2026-04-25）では見逃されていた実際の参照切れを2件検出しました。

• attune:makefile-generation -> abstract:makefile-dogfooder （スクリプト名をスキル名と取り違え）
• imbue:karpathy-principles -> spec-kit:speckit-clarify （コマンドをスキルとして参照）

どちらも同じセッション内で、正しいコマンド形式の参照に修正されました。

検証

監査出力の信頼性を検証する方法は2つあります。

1. テストスイートの正確性チェック：pytest -o addopts= plugins/abstract/tests/scripts/test_skill_graph.py を実行し、抽出、グラフ構築、順位付け、孤立ノード検出、参照切れの分類が、現在のコードですべて成功することを確認します。-o addopts= フラグはパッケージ全体に適用されるカバレッジ要件を回避します。この要件は、単一ファイルだけを実行すると失敗するためです。
2. ラウンドトリップのスモークチェック：ベースライン実行時の参照切れ件数を記録し、指摘された参照を1件以上修正してから再実行し、件数が修正数以上減少していることを確認します。件数が変わらない場合、レポートが古いか、正規表現が構文のバリエーションを見逃しています。

完了条件

• 監査実行前に、仕込まれたフィクスチャテストが成功していること。これがなければ、plugins/ の問題のないレポートを監査結果として報告できません
• グラフが構築されること：skill_graph.py が plugins/ に対してエラーなく実行され、ノード数とエッジ数を出力すること。
• 参照切れがバグ、外部、プレースホルダーに分類されること（「主な出力」の3行に対応）。
• 「参照切れ：バグ」の各項目が、同じセッション内で修正されるか、追跡対象の課題として登録されていること。
• pytest -o addopts= plugins/abstract/tests/scripts/test_skill_graph.py が成功すること。
• ラウンドトリップのスモークチェックで、参照切れ件数が修正した参照数以上減少すること。

関連スキル

• Skill(abstract:skills-eval)：スキルごとの品質評価
• Skill(abstract:plugin-review)：プラグインのマニフェストと構造
• Skill(abstract:hooks-eval)：フック固有の検証
• Skill(abstract:rules-eval)：rules ディレクトリの検証

参考資料

• 実装：plugins/abstract/scripts/skill_graph.py
• テスト：plugins/abstract/tests/scripts/test_skill_graph.py
• 構成のドキュメント： docs/quality-gates.md#skill-level-quality-gate-composition
• スキルの役割の分類：docs/skill-integration-guide.md#skill-role-taxonomy