health-plugins

/health:plugins

Claude Code のプラグインレジストリの問題を診断して修正します。このコマンドは、プロジェクトスコープのプラグインがグローバルにインストール済みとして誤って表示される問題 #14202 に特化して対処します。

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

このスキルを使用する場合...	別の方法を使用する場合...
プラグインレジストリの破損を修正する場合（問題 #14202）	包括的なヘルスチェックを行う場合（/health:check を使用）
プロジェクトスコープとグローバルのプラグインに関する問題を診断する場合	プラグインの関連性を監査する場合（/health:audit を使用）
孤立したプラグインエントリを整理する場合	設定の検証だけが必要な場合
「プラグインはすでにインストールされています」というエラーを解決する場合	エージェント型の最適化監査を行う場合（/health:agentic-audit を使用）
レジストリの JSON を手動で調べる場合	インストール済みプラグインを表示するだけの場合（レジストリファイルを読む）

コンテキスト

• 現在のプロジェクト：!pwd
• 現在のプロジェクトにプラグインがある場合：!find . -maxdepth 2 -path '*/.claude-plugin/plugin.json' -type f
• プロジェクト設定が存在する場合：!find . -maxdepth 1 -name '.claude/settings.json'
• プロジェクトのプラグインディレクトリ：!find . -maxdepth 1 -type d -name '.claude-plugin'

背景：問題 #14202

あるプロジェクトで --scope project を指定してプラグインをインストールすると、他のプロジェクトでもマーケットプレイスのビューにそのプラグインが「（インストール済み）」と誤って表示されます。これは、次の理由によるものです。

1. ~/.claude/plugins/installed_plugins.json のプラグインレジストリには、プロジェクトスコープでインストールした場合の projectPath が保存されます
2. マーケットプレイスのビューは、プラグインキーが存在するかどうかだけを確認し、現在のプロジェクトにインストールされているかどうかは確認しません
3. プラグインがすでに存在すると判断されるため、インストールコマンドはインストールを拒否します

影響：ユーザーは、プロジェクトスコープの分離を保ったまま、複数のプロジェクトに同じプラグインをインストールできません。

パラメーター

$ARGUMENTS から次の内容を解析します。

パラメーター	説明
--fix	プラグインレジストリに修正を適用します
--dry-run	変更を加えず、修正内容を表示します
--plugin <name>	特定のプラグインのみを確認／修正します

実行

以下のスクリプトを実行して、このプラグインレジストリの診断を行います。指定されている場合は、$ARGUMENTS の --plugin <name> をそのまま渡します。

ステップ 1：レジストリを診断する

bash "${CLAUDE_SKILL_DIR}/scripts/check-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--plugin <name>] [--verbose]

出力から STATUS=、PLUGIN_COUNT=、ORPHANED_ENTRIES=、および ISSUES: の行を解析します。=== PLUGINS === セクションには、インストール済みプラグインごとのスコープ、バージョン、ソース、projectPath が一覧表示されます。

ステップ 2：調査結果を報告する

次の内容をまとめた構造化診断レポートを出力します。

1. レジストリの場所、有効性、およびプラグイン数（合計／グローバル／プロジェクトスコープ）
2. 孤立したエントリ（projectPath のディレクトリが存在しないもの）。重大度と推奨される修正を含めます
3. 設定で有効になっているが、レジストリにはないプラグイン
4. 他のプロジェクトのプラグイン（INFO のみ。--verbose を指定した場合に表示）

問題の確定リストとして、ISSUES: の行を使用します。

ステップ 3：修正を適用する（--fix の場合）

$ARGUMENTS に --fix が含まれている場合：

1. --dry-run も指定されている場合を除き、削除する孤立プラグインを AskUserQuestion 経由でユーザーに確認します。

2. 修正スクリプトを実行します。

   bash "${CLAUDE_SKILL_DIR}/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--plugin <name>] [--dry-run]
   

   スクリプトはレジストリを変更する前に、~/.claude/plugins/installed_plugins.json.backup.<UTC-timestamp> にタイムスタンプ付きのバックアップを作成し、変更後の JSON を検証します。エラーが発生した場合は安全に中止します。

3. STATUS=、REMOVED=、REMOVED_COUNT=、および BACKUP_PATH= の行を解析し、変更内容を報告します。

4. 修正の永続性に関する警告を伝えます。 出力に SETTINGS_CHEZMOI_MANAGED=true が含まれている場合は、WARNING= の行をユーザーに伝えます。編集した ~/.claude/settings.json は chezmoi によって管理されているため、chezmoi のソースから同じキーも削除しない限り、次回の chezmoi apply で修正が元に戻ります。ソースの場所は SETTINGS_CHEZMOI_SOURCE= として出力されます。

ステップ 4：現在のプロジェクトで「プラグインが必要」な場合の対応

異なる projectPath でレジストリに登録されているプラグインを現在のプロジェクトで利用したい場合は、AskUserQuestion を使って確認してから、次の操作を行います。

1. Edit ツールを使って、.claude/settings.json の enabledPlugins に新しいエントリを追加します。
2. レジストリに正しく登録するため、Claude Code の UI から /plugin install を実行するようユーザーに案内します。

ステップ 5：修正を確認する

修正を適用した後、ステップ 1 を再実行し、問題の件数が減っていることを確認します。変更を反映するには Claude Code の再起動が必要であることをユーザーに案内します。

レジストリ構造の参照

{
  "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" — projectPath があり、そのプロジェクト内でのみ有効です
• "scope": "user" — projectPath がなく、全体で有効です

手動での回避策

自動修正に失敗した場合、ユーザーは ~/.claude/plugins/installed_plugins.json を手動で編集できます。

1. ファイルをエディターで開きます
2. プラグインのエントリを見つけます
3. 次のいずれかを行います。
   • projectPath を削除して、全体で有効にします
   • projectPath を現在のプロジェクトのパスに変更します
   • 現在のプロジェクト用に別のキーで新しいエントリを追加します
4. 保存して Claude Code を再起動します

エージェント向けの最適化

コンテキスト	コマンド
プラグインレジストリの診断	/health:plugins
レジストリの問題を修正	/health:plugins --fix
ドライランモード	/health:plugins --dry-run
診断のみ（スクリプト）	bash "${CLAUDE_SKILL_DIR}/scripts/check-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)"
修正のみ（スクリプト）	bash "${CLAUDE_SKILL_DIR}/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)"

フラグ

フラグ	説明
--fix	修正を適用します（確認プロンプトが表示されます）
--dry-run	変更を加えず、修正内容を表示します
--plugin <name>	特定のプラグインを対象にします

関連項目

• /health:check - 診断スキャン全体
• /health:settings - 設定ファイルの検証
• Issue #14202 - 上流のバグ報告