plugin-registry

Claude Code プラグインレジストリ

Claude Code プラグインレジストリを理解し、トラブルシューティングするための専門知識です。

このスキルを使用するタイミング

次の場合にこのスキルを使用します…	次の場合は別のものを使用します…
プラグインに「インストール済み」と表示されるが、動作しない	新しいプラグインをセットアップする場合（/configure:claude-plugins を使用）
プラグインのスコープを理解する必要がある	プラグインの権限を設定する場合（settings-configuration スキルを使用）
孤立したレジストリエントリを修正する場合	プラグインを使用してワークフローを作成する場合（github-actions-plugin を使用）
インストールの失敗をデバッグする場合

レジストリの場所

プラグインレジストリは次の場所に保存されています。

~/.claude/plugins/installed_plugins.json

このファイルは、すべてのプロジェクトにインストールされたプラグインを追跡します。

レジストリの構造（v2）

{
  "version": 2,
  "plugins": {
    "plugin-name@marketplace-name": [
      {
        "scope": "project",
        "projectPath": "/path/to/project",
        "installPath": "~/.claude/plugins/cache/marketplace/plugin-name/1.0.0",
        "version": "1.0.0",
        "installedAt": "2024-01-15T10:30:00Z",
        "lastUpdated": "2024-01-15T10:30:00Z",
        "gitCommitSha": "abc123"
      }
    ]
  }
}

各プラグインキーは、インストールの配列に対応します（複数のスコープをサポート）。

フィールドの説明

フィールド	必須	説明
scope	はい	"project" または "user"（グローバル）
projectPath	プロジェクトのみ	プラグインが有効なディレクトリ
installPath	はい	インストール済みプラグインファイルのキャッシュパス
version	はい	インストール済みのバージョン
installedAt	はい	インストール日時の ISO タイムスタンプ
lastUpdated	はい	最終更新日時の ISO タイムスタンプ
gitCommitSha	はい	インストール済みバージョンの Git コミット

インストールのスコープ

ユーザースコープ（グローバル、デフォルト）

/plugin install my-plugin@marketplace

• レジストリエントリで "scope": "user" を指定
• projectPath フィールドなし
• すべてのプロジェクトで利用可能

プロジェクトスコープ

/plugin install my-plugin@marketplace --scope project

• レジストリエントリで "scope": "project" を指定
• projectPath にインストールディレクトリを設定
• そのプロジェクトでのみ有効になるはずです
• Bug #14202：ほかのプロジェクトでも「インストール済み」と表示されます

既知の問題：#14202

問題：プロジェクトスコープのプラグインが、誤ってグローバルにインストール済みとして表示されます。

根本原因：projectPath のチェックに一貫性がありません。

操作	projectPath をチェックするか	結果
マーケットプレイスの「（インストール済み）」表示	いいえ	どのプロジェクトでもインストール済みと表示
/plugin install	いいえ	インストールを拒否
インストール済みタブの一覧	はい	正しく絞り込み

症状：

1. マーケットプレイスビューで、プラグインに「（インストール済み）」のチェックマークが表示される
2. /plugin install が「すでにインストール済み」と表示する
3. 現在のプロジェクトの「インストール済み」タブにプラグインが表示されない
4. プラグインが現在のプロジェクトで実際には動作しない

回避策：レジストリを手動で編集し、現在のプロジェクトのエントリを追加します。

レジストリの手動操作

レジストリを表示する

jq . ~/.claude/plugins/installed_plugins.json

すべてのプラグインを一覧表示する

jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json

プロジェクトスコープのプラグインを検索する

jq '.plugins | to_entries[] | .value[] | select(.scope == "project") | {projectPath, version}' ~/.claude/plugins/installed_plugins.json

孤立したエントリを検索する

Read ツールを使用して ~/.claude/plugins/installed_plugins.json を読み込み、各 projectPath に対して test -d を実行します。

レジストリをバックアップする

cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup

レジストリの問題を修正する

孤立したエントリを削除する

1. Read ツールを使用して ~/.claude/plugins/installed_plugins.json を読み込みます
2. cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup でバックアップを作成します
3. plugins オブジェクトから孤立したエントリを削除します
4. Write ツールを使用して更新した JSON を書き込みます

現在のプロジェクトのエントリを追加する

1. Read ツールを使用してレジストリを読み込みます
2. プラグインの配列に scope: "project" と現在の projectPath を指定した新しいエントリを追加します
3. Write ツールを使用して更新した JSON を書き込みます

プロジェクトスコープをユーザー（グローバル）に変換する

1. Read ツールを使用してレジストリを読み込みます
2. "scope": "project" を "scope": "user" に変更し、projectPath を削除します
3. Write ツールを使用して更新した JSON を書き込みます

プロジェクト設定との連携

プロジェクトスコープのプラグインには、.claude/settings.json のエントリも必要です。

{
  "enabledPlugins": [
    "plugin-name@marketplace"
  ]
}

これがないと、正しく登録されたプロジェクトスコープのプラグインも読み込まれません。

トラブルシューティング チェックリスト

1. プラグインがインストール済みと表示されるが、動作しない

   • projectPath が現在のディレクトリと一致しているか確認します
   • .claude/settings.json の enabledPlugins を確認します
   • /health:plugins を実行して診断します

2. プラグインをインストールできない（すでにインストール済み）

   • レジストリに既存のエントリーがないか確認します
   • エントリーの projectPath が異なるか確認します
   • /health:plugins --fix を使用するか、手動で編集します

3. あるプロジェクトではプラグインが動作するが、別のプロジェクトでは動作しない

   • プロジェクトスコープのプラグインである可能性があります
   • プロジェクトごとに個別のレジストリエントリーが必要です
   • または、グローバルスコープに変更します

4. レジストリファイルが破損している

   • バックアップがある場合は、そこから復元します
   • または、プラグインを削除して再インストールします
   • 場所：~/.claude/plugins/installed_plugins.json

エージェント向け最適化

コンテキスト	コマンド
レジストリを表示	jq -c . ~/.claude/plugins/installed_plugins.json
プラグインを一覧表示	jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json
特定のプラグインを確認	jq '.plugins."name@market"' ~/.claude/plugins/installed_plugins.json
プロジェクトのプラグイン	jq '.plugins | to_entries[] | .value[] | select(.scope=="project")' ~/.claude/plugins/installed_plugins.json

クイックリファレンス

レジストリのパス

~/.claude/plugins/installed_plugins.json

キーの形式

{plugin-name}@{marketplace-name}

スコープの指定

• "scope": "project" + projectPath → プロジェクトスコープ
• "scope": "user" → グローバル（ユーザー全体）

編集後

レジストリの変更を反映するには、必ず Claude Code を再起動してください。