claude-skills-troubleshooting

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

概要

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

すばやく診断する

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

python3 scripts/diagnose_plugins.py

スクリプトでは、次の項目を確認します。

• インストール済みプラグインと有効なプラグインの不一致（インストール済みだが有効化されていない場合、および有効化されているが登録されていない場合の両方）
• settings.json に enabledPlugins エントリがない
• known_marketplaces.json の lastUpdated を使用した、古いマーケットプレースキャッシュ
• lastUpdated メタデータがない、不正な形式、タイムゾーンがない、または未来の日付になっている
• 無効なプラグイン設定

キャッシュの鮮度を判断する唯一の情報源として lastUpdated を使用してください。 キャッシュディレクトリの更新時刻にはフォールバックしないでください。マーケットプレースの更新によってネストされたファイルが更新されても、ディレクトリのタイムスタンプは変化しない場合があります。キャッシュが古い場合、または鮮度メタデータが無効な場合、診断スクリプトはゼロ以外の終了コードを返します。

よくある問題

問題 1：プラグインがインストールされているのに、使用可能なスキルに表示されない

症状：

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

根本原因： 既知のバグ（GitHub #17832）により、プラグインは installed_plugins.json に追加されますが、settings.json の enabledPlugins には自動的に追加されません。

診断：

# Check if plugin is in installed_plugins.json
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"

# Check if plugin is enabled in settings.json
cat ~/.claude/settings.json | grep "plugin-name"

解決方法：

# Option 1: Use CLI to enable
claude plugin enable plugin-name@marketplace-name

# Option 2: Manually edit settings.json
# Add to enabledPlugins section:
# "plugin-name@marketplace-name": true

逆のケース — 有効化されているが登録されていない： 診断結果でプラグインが enabledPlugins には存在するものの、installed_plugins.json には存在しない場合、原因はシンボリックリンクのスキップバグです。複数のプロファイルで共有する設定で、installed_plugins.json がシンボリックリンクになっている設定ディレクトリの下でインストールが実行され、CLI がファイルへの書き込みを黙ってスキップしました。references/known_issues.md の「Symlinked installed_plugins.json」を参照してください。次のように修正します。

# Reinstall from the config dir owning the real file
CLAUDE_CONFIG_DIR=~/.claude claude plugin install plugin-name@marketplace-name

# Then confirm
claude plugin list

問題 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 に最新の変更がある
• インストール時にプラグインが見つかるものの、古いバージョンが取得される
• 新しく追加したプラグインが表示されない

解決方法：

# Update marketplace cache
claude plugin marketplace update marketplace-name

# Or clear and re-fetch
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 で明示的に呼び出せます
   • Skill ツールの利用可能な一覧に表示されます
   • コマンドファイル（例：commands/seer.md）が必要です

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

参考資料

• GitHub の課題管理については、references/known_issues.md を参照してください
• プラグインのアーキテクチャの詳細については、references/architecture.md を参照してください