スキルグラフ

Claude Code プラグイン。あなたがすでに持っているスキルとエージェントを、セッション中、ブラウザ、またはデスクトップアプリからクエリ可能なグラフに変換します。

指定したフォルダ内のすべてのエージェントとスキルをカタログ化し、それらのうち実際に他のものを参照しているものをカウントし、マシン上でそれぞれが実際にインストールされているプロジェクトをスキャンし、そのすべてをMCPツールとして公開します。すべての情報は実際のファイルを読み取ることで得られます。

任意のノードをクリックすると、それを参照しているもの、それが参照しているもの、インストールされているプロジェクト、そしてあなた自身のメモ、評価、タグが表示されます：

インストール

/plugin marketplace add QuantumWars/project-graphx
/plugin install skill-graph

次に、グラフを作成したい任意のプロジェクトで：

/skill-graph:setup     # say where your skills and agents live — then offers to build
/skill-graph:build     # rescan, whenever the sources change
/skill-graph:view      # look at it, in your browser

/skill-graph:setup は、単に実行するのではなく、ビルド前に確認を求めます。これは、scanRoots が設定されたビルドがすべてのスキャンルートを走査するためです。はいを選択すると、何もない状態から直接グラフに進みます。

各プロジェクトは独自のグラフを持ちます。すべてのプロジェクトで共有される1つのカタログが必要な場合は、代わりに /skill-graph:setup-global を実行してください。詳細は「1つのグラフ、またはプロジェクトごとに1つ」を参照してください。

/skill-graph:view はダウンロードを必要としません。プラグインがすでに必要とする node からビューアを提供します。/skill-graph:app は代わりに同じビューアをネイティブデスクトップウィンドウとして開きますが、その代償として約280 MBのElectronを一度だけインストールする必要があります。

Related MCP server: skills-mcp

必要条件

Windowsは /skill-graph:build でサポートされていません。 ビルドコマンドは python3 を呼び出しますが、WindowsのPythonインストールでは通常提供されません（python または py です）。install_skill も同じ依存関係を持ち、ファイルコピー 後 に失敗するため、中途半端な状態を残す可能性があります。WSLは動作します。

デスクトップアプリのパッケージングスクリプトは macOS arm64のみ を対象としています。他のプラットフォームでは /skill-graph:view を使用するか、app/ から npm start でパッケージ化せずに実行してください。

1つのグラフ、またはプロジェクトごとに1つ

デフォルトでは、データディレクトリは <project>/.claude/graph であるため、2つのプロジェクトが互いのグラフを見ることはありません。これは通常望ましい動作であり、無関係なリポジトリ間で何も追跡されない理由でもあります。

GRAPH_DATA_DIR でこれを上書きできます。設定すると、すべてのプロジェクトが同じディレクトリを読み書きします：

dataDir = GRAPH_DATA_DIR  or  <project>/.claude/graph

/skill-graph:setup-global はこれをエンドツーエンドで実行します。場所を選択し、マシン上のすべてのソースを見つけ、絶対ルートで設定を書き込み、~/.claude/settings.json に変数を設定し、ビルドします。これは次回の再起動時に有効になります。MCPサーバーはプロセス起動時に環境を読み取るためです。

ディレクトリを共有するとオーバーレイも共有されるため、メモ、評価、タグはリポジトリごとではなくマシン全体に適用されます。同じ スキル をどこでも使用したいが、同じ メモ は使用したくない場合は、変数を設定しないでください。各プロジェクトに、ソースルートが 絶対パス である通常の設定を指定します。相対ルートはプロジェクトに対して解決されます。絶対ルートは解決されないため、複数のプロジェクトが同じフォルダをカタログ化しつつ、独自のグラフを保持できます。

プロジェクトごとのグラフは、グローバルにしても削除されません。変数を削除すると、再び有効になります。

ファイルの配置場所

コードはプラグインとともに提供されます。データはプロジェクトに属します：

<your project>/.claude/graph/
├── config.json        what to catalogue, what to scan   (you own this — commit it)
├── graph-data.json    the built graph                   (regenerated wholesale)
├── overlay.json       your notes, ratings, tags, edges  (survives rebuilds)
└── imported-repos/    shallow clones from add_repo

グラフデータがプラグインディレクトリに書き込まれることは決してありません。プラグインディレクトリは再インストールのたびに消去されます。同じマシン上の2つのプロジェクトは、2つの独立したグラフを取得し、互いのグラフを見ることはありません。

唯一の例外はElectron自体です。/skill-graph:app はプラグインの app/ の下にインストールするため、プラグインを更新すると再度ダウンロードする必要があります。/skill-graph:view は再インストールするものが何もないため、これがデフォルトである主な理由です。

graph-data.json は /skill-graph:build が実行されるたびにゼロから再構築されます。手動で編集しないでください。編集内容は消えます。ツールを通じて追加したものはすべて overlay.json に保存され、ビルドが触ることはありません。

設定

.claude/graph/config.json：

{
  "sources": [
    { "repo": "my-project", "root": ".claude/agents", "kind": "agent" },
    { "repo": "my-project", "root": ".claude/skills", "kind": "skill" }
  ],
  "scanRoots": ["~/code"],
  "scanExclude": ["/node_modules/"]
}

• sources — カタログ化するエージェントとスキルが含まれるディレクトリ。*.md ファイルのフォルダの場合は kind: "agent"、<name>/SKILL.md ディレクトリのフォルダの場合は kind: "skill"。相対パスはプロジェクトルートに対して解決されます。ルートが見つからない場合はクラッシュせずに警告とともにスキップされます。

• scanRoots — それらのスキルがインストールされているプロジェクトを検索するツリー。これにより「誰が実際にこれを使用しているか」が埋められます。[] は何もスキャンしないことを意味し、そのまま尊重されます。

• scanExclude — これらの部分文字列のいずれかを含むパスを除外します。

設定されたソースを所有するプロジェクトは、自身のカタログのユーザーとしてカウントされることはありません。これがないと、自身の .claude/skills をカタログ化するリポジトリは、その中のすべてのスキルのユーザーとして自身を報告し、すべての使用数が1つ水増しされることになります。

ツールが教えてくれること、教えてくれないこと

エッジはカウントされた言及です。 エッジが存在するのは、あるファイルのテキストに別のノードの名前が含まれているからです。これは実際の再現可能な測定値であり、2つのものが一緒に属するという厳選されたステートメントではありません。一般的な単語にちなんで名付けられたスキルは、偶然によってエッジを収集します。

使用状況はファイルシステム上の事実です。 usedBy は、ファイルが実際に存在するかどうかを確認することで得られます。存在しない場合は「スキャンルートの下に見つかりませんでした」を意味し、「未使用」を意味するものではありません。

カテゴリは推測です。 ビルド時のキーワードヒューリスティックから得られます。これは最初に名前を読み、名前が何も示さない場合にのみ説明にフォールバックします。python-testing という名前のものはPythonですが、単にPythonに 言及している だけのものはPythonではありません。それでもヒューリスティックです。一部のものを奇妙に分類し、判断できない場合は general と表示します。タグは手動で適用され、誰かが決定した意味を持ちます。タグを優先してください。

インポートされたリポジトリにはエッジがありません。 add_repo はフロントマターのみを抽出します。相互参照はインポートに対して計算されません。インポートされたスキルにおけるゼロ接続は、スキルについてではなく、インポーターについてのステートメントです。これが、すでにソースとして設定したディレクトリをインポートすることが無意味以上であり、拒否される理由でもあります。以下を参照してください。

2つのものが同じ名前を共有する場合

無関係な2つのリポジトリがそれぞれ code-reviewer を保持している可能性があり、両方ともグラフに属します。したがって、名前による検索は真に曖昧になる可能性があり、その場合、回答は代わりにIDを指定します：

{ "error": "ambiguous", "candidates": ["myproj:agent:code-reviewer", "import:other:agent:code-reviewer"] }

ノードを受け取るすべてのツールはIDも受け入れるため、そのリストからの候補を直接渡して同点を解決できます。これには install_skill と uninstall_skill も含まれ、間違ったものを選択すると実際のファイルがコピーまたは削除されます。

add_repo は、ビルドがすでにカタログ化しているディレクトリを拒否します。 両方のルートが同じファイルに到達します。ビルドはそれらを graph-data.json に書き込み、インポートはそれらを overlay.json に保存し、読み取り時に2つがマージされるため、その下のすべてのアイテムが1つの名前で2回表示され、IDで区別できなくなります。なぜなら、それらは 同じファイル だからです。何かを書き込む前に停止し、すでにグラフにあるファイルを指定して「何もインポートされませんでした」と表示します。

たまたまスキル名が同じである2つの異なるリポジトリは問題なく、引き続きインポートできます。チェックはパスに対して行われ、名前に対してではありません。

グラフはスナップショットです

最後のビルドの状態を反映します。手動でスキルを追加したり、ソースを変更したり、これらのツールの外部で何かをインストールしたりすると、再ビルドするまで古いままです。install_skill と uninstall_skill は自身を再スキャンしますが、他のツールは何もしません。

開発

bun install --frozen-lockfile   # exactly the versions CI and the bundle were built from
bun test                        # unit + end-to-end
bun run bundle                  # rebuild server/server.bundle.mjs after editing server/

bun.lock はコミットされたバンドルのコンパイル元を固定し、app/package-lock.json はデスクトップアプリがテストされたElectronを固定します。CIは --frozen-lockfile でインストールするため、ロックファイルを更新せずに依存関係をバンプすると、静かに出荷される代わりに実行が失敗します。

ビューアは直接実行できます。これは app/ を反復する最も速い方法です：

node server/viewer-server.js --data-dir <project>/.claude/graph

server/ 下で変更を行った後は、必ず再バンドルしてください。 .mcp.json はソースではなくバンドルを実行するため、バンドルされていない編集は出荷されない編集です。エンドツーエンドスイートは、Claude Codeとまったく同じようにバンドルを起動し、古い場合は失敗します。CIはそれを再ビルドし、コミットされたコピーと異なる場合は失敗します。

bun run bundle は scripts/normalize-bundle.js も実行します。これは、バンドラーがビルド時に凍結する __dirname リテラルを、ランタイム式に置き換えます。これがないと、アーティファクトはビルドした人の絶対パスを保持し、2台のマシンで同じバイトが生成されることはありません。これにより、CI比較が可能になります。

ライセンス

MIT — LICENSE を参照してください。