Claude Skills トラブルシューティング

概要

Claude Code プラグインとスキル設定の一般的な問題を診断・解決します。このスキルは、プラグインのインストール、有効化、アクティベーションの問題に関する体系的なデバッグワークフローを提供します。

クイック診断

診断スクリプトを実行して一般的な問題を特定します:

python3 scripts/diagnose_plugins.py

スクリプトは以下をチェックします:

• インストール済みプラグインと有効化されたプラグインの不一致
• settings.json の enabledPlugins エントリの欠落
• 古いマーケットプレイスキャッシュ
• 無効なプラグイン設定

よくある問題

問題 1: プラグインがインストール済みだが、利用可能なスキルに表示されない

症状:

• /plugin でプラグインがインストール済みと表示される
• スキルツールの利用可能スキルリストに表示されない
• プラグインメタデータが installed_plugins.json に存在する

根本原因: 既知のバグ (GitHub #17832) - プラグインが installed_plugins.json に追加されますが、自動的に settings.json の enabledPlugins に追加されません。

診断:

# プラグインが installed_plugins.json にあるか確認
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"

# プラグインが settings.json で有効化されているか確認
cat ~/.claude/settings.json | grep "plugin-name"

解決策:

# オプション 1: CLI を使用して有効化
claude plugin enable plugin-name@marketplace-name

# オプション 2: settings.json を手動編集
# enabledPlugins セクションに追加:
# "plugin-name@marketplace-name": true

問題 2: プラグイン状態アーキテクチャの理解

主要ファイル:

ファイル	目的
~/.claude/plugins/installed_plugins.json	すべてのプラグインのレジストリ(インストール済み + 無効化)
~/.claude/settings.json → enabledPlugins	どのプラグインがアクティブかを制御
~/.claude/plugins/known_marketplaces.json	登録済みマーケットプレイスソース
~/.claude/plugins/cache/	実際のプラグインファイル

プラグインがアクティブになる条件:

1. installed_plugins.json に存在する(登録済み)
2. settings.json → enabledPlugins に値 true でリストされている

問題 3: マーケットプレイスキャッシュが古い

症状:

• GitHub に最新の変更がある
• インストールはプラグインを見つけるが古いバージョンを取得
• 新しく追加されたプラグインが表示されない

解決策:

# マーケットプレイスキャッシュを更新
claude plugin marketplace update marketplace-name

# またはクリアして再取得
rm -rf ~/.claude/plugins/cache/marketplace-name
claude plugin marketplace update marketplace-name

問題 4: マーケットプレイスでプラグインが見つからない

一般的な原因(可能性が高い順):

1. ローカル変更が GitHub にプッシュされていない - 最も一般的!

   git status
   git push
   claude plugin marketplace update marketplace-name
   

2. marketplace.json 設定エラー

   python3 -m json.tool .claude-plugin/marketplace.json
   

3. スキルディレクトリが見つからない

   ls -la skill-name/SKILL.md
   

診断コマンド リファレンス

目的	コマンド
マーケットプレイスをリスト表示	claude plugin marketplace list
マーケットプレイスを更新	claude plugin marketplace update {name}
プラグインをインストール	claude plugin install {plugin}@{marketplace}
プラグインを有効化	claude plugin enable {plugin}@{marketplace}
プラグインを無効化	claude plugin disable {plugin}@{marketplace}
プラグインをアンインストール	claude plugin uninstall {plugin}@{marketplace}
インストール済みを確認	cat ~/.claude/plugins/installed_plugins.json | jq '.plugins | keys'
有効化済みを確認	cat ~/.claude/settings.json | jq '.enabledPlugins'

一括有効化 不足しているプラグイン

マーケットプレイスからインストール済みだが無効化されているすべてのプラグインを有効化します:

python3 scripts/enable_all_plugins.py marketplace-name

スキル対 コマンド アーキテクチャ

Claude Code には 2 種類のユーザーが呼び出し可能な拡張機能があります:

1. スキル (skills/ ディレクトリ内)

   • 説明に基づいてスキルが自動アクティブ化
   • ユーザーリクエストがスキル説明に一致するときにロード

2. コマンド (commands/ ディレクトリ内)

   • /command-name 経由で明示的に呼び出し可能
   • スキルツールの利用可能リストに表示
   • コマンドファイルが必要 (例: commands/seer.md)

スキルを明示的に呼び出し可能にする場合は、対応するコマンドファイルを追加してください。

参考資料

• GitHub の問題追跡については references/known_issues.md を参照
• 詳細なプラグインアーキテクチャについては references/architecture.md を参照