health-check

/health:check

Claude Code のヘルス診断への単一のエントリーポイントです。環境チェック（プラグインレジストリ、設定、フック、MCP サーバー、SessionStart の実行可能性、pre-commit の有効性、権限の網羅状況、マーケットプレイスへの登録）に加え、任意の詳細監査を実行し、--fix を適切な内部ワークフローに振り分けます。

このスキルを使用する場面

次の場合にこのスキルを使用します...	次の場合は別の方法を使用します...
Claude Code の診断を実行する	生の設定を確認する（settings.json に Read を使用）
プラグインレジストリの問題をトラブルシューティングする	マーケットプレイスのメタデータを手動で調べる
プロジェクトへの適合性についてプラグインを監査する	特定のプラグインをインストールする（/plugin install を使用）
スキルのエージェント最適化品質を確認する	既知の単一スキルを編集する
レジストリ／スタック／エージェント最適化を対象に一括で --fix を実行する	単一ファイルに対して正確な修正を行う

コンテキスト

• 現在のプロジェクト：!pwd
• プロジェクト設定の有無：!find . -maxdepth 2 -path '*/.claude/settings.json'
• ローカル設定の有無：!find . -maxdepth 2 -path '*/.claude/settings.local.json'

パラメーター

$ARGUMENTS から以下を解析します。

パラメーター	説明
--scope=<all|registry|stack|agentic|runtime|usage>	実行する監査。既定値は all です。
--fix	検出事項を修正します（確認を求めます）。
--dry-run	ファイルを変更せずに修正内容をプレビューします。
--verbose	詳細な診断情報を含めます。

スコープの意味：

スコープ	対象
registry	プラグインレジストリの健全性（孤立した projectPath、古い enabledPlugins、レジストリと設定の不一致）
stack	有効なプラグインと検出されたプロジェクトの技術スタックの比較
agentic	スキル／コマンド／エージェントのエージェント最適化への準拠
runtime	~/.claude.json の肥大化（不要な projects[]、不要な githubRepoPaths[*]、孤立した disabledMcpServers、重複した MCP 名）。読み取り専用の監査です。
usage	~/.claude/projects/*/*.jsonl のセッションテレメトリーを分析し、一度も呼び出されていないスキルと休眠中のスキルおよびプラグインエージェントを特定します。読み取り専用でローカル環境を重視し、履歴が不十分な場合はスキップします。
all	環境チェックと5つすべての監査

実行

この診断ルーターを実行します。--scope が指定されていない場合、既定のスコープは all です。

ステップ 1：環境チェックを実行する（常時）

環境チェックは --scope にかかわらず実行されます。Claude Code のインストールと、現在のプロジェクトの .claude/ ディレクトリの基本的な健全性を確認します。

1a. コア環境スクリプト

bash "${CLAUDE_SKILL_DIR}/scripts/check-plugins.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-settings.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-hooks.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-mcp.sh" --home-dir "$HOME" --project-dir "$(pwd)"

それぞれから STATUS= と ISSUES: を解析します。$ARGUMENTS に --verbose が設定されている場合は、そのオプションを渡します。

check-settings.sh が PROJECT_DIR_RESOLVED=<path> を出力した場合、ワークスペースのルートには .claude/ がありませんでしたが、1階層下に単一の */.claude/settings.json が見つかったことを示しています（親ワークスペース／モノレポ構成）。どの設定が確認されたかユーザーが把握できるよう、レポートに解決されたパスを記載します。PROJECT_DIR_HINT=<msg> が出力された場合は、そのヒントを提示します。複数のネストされた設定が見つかったため、対象を指定するには --project-dir を付けて再実行する必要があります。

1b. SessionStart のスモークテスト

scripts/install_pkgs.sh（または .claude/settings.json の SessionStart フックに登録されたスクリプト）が実行可能であり、リモート環境とローカル環境の両方で正常に終了するかを確認します。

1. .claude/settings.json から SessionStart フックのコマンドを特定します（command フィールドを確認します）。
2. スクリプトが見つかった場合は、次を実行します。

   CLAUDE_CODE_REMOTE=true bash <script-path>
   

   終了コードを記録します。期待値：0。
3. 冪等性を確認するためにもう一度実行します。期待値：0。
4. リモートガードをオフにして実行します。

   CLAUDE_CODE_REMOTE=false bash <script-path>
   

   期待値：0（通常は何も行いません）。
5. 次のように報告します。
   • OK：3回すべての終了コードが0
   • WARN：スクリプトは存在するものの、settings.json のフックに登録されていない
   • ERROR：スクリプトの終了コードが0以外、またはフックで参照されているスクリプトが存在しない

1c. Pre-commit 設定の検証

.pre-commit-config.yaml が存在する場合：

pre-commit validate-config .pre-commit-config.yaml

報告：

• OK：終了コード 0（設定は有効です）
• WARN：pre-commit がインストールされていません — チェックをスキップし、pip install pre-commit を提案します
• ERROR：終了コードが 0 以外 — 検証エラーを表示します

1d. 権限の網羅性チェック

プロジェクトファイル内で参照されているツールと、.claude/settings.json の permissions.allow を比較します。

1. .claude/settings.json から permissions.allow を読み込みます。各 Bash(<prefix>:*) エントリからコマンドのプレフィックスを抽出します。
2. 次のファイルをスキャンして、ツールの呼び出しを確認します。
   • justfile / Justfile — レシピ行のコマンド
   • Makefile — レシピ行のシェルコマンド
   • .pre-commit-config.yaml — entry: フィールド
3. プロジェクトファイルで見つかった各ツールについて：
   • permissions.allow に一致する Bash(<tool>:*) エントリがない場合、MISSING としてフラグを付けます
4. permissions.allow にある各 Bash(<tool>:*) エントリについて：
   • どのプロジェクトファイルにもそのツールが見つからない場合、UNUSED としてフラグを付けます（情報提供のみで、エラーではありません）

スコア：

• OK：不足している権限はありません
• WARN：不足している権限が 1～3 件あります
• ERROR：不足している権限が 4 件以上あります

1e. マーケットプレイス登録チェック

ローカルのマーケットプレイスキー（claude marketplace add <name> で設定）はユーザーが選択するため、インストールごとに異なります（一般的には laurigates-claude-plugins、場合によっては claude-plugins）。固定のローカルキーではなく、安定した source.repo に基づいてマーケットプレイスを特定します。

1. .claude/settings.json を読み込みます。
2. extraKnownMarketplaces 内のすべてのエントリを調べ、source.repo が "laurigates/claude-plugins" と一致するものを見つけます。そのエントリのキーを $MP_KEY として取得します。
3. enabledPlugins に接尾辞 @$MP_KEY を持つキーが少なくとも 1 つ含まれていることを確認します。
4. 報告：
   • OK：両方のチェックに合格しています
   • WARN：enabledPlugins に @$MP_KEY を含むエントリがありません（マーケットプレイスには登録済みですが、プラグインは有効になっていません）
   • ERROR：source.repo = laurigates/claude-plugins を持つ extraKnownMarketplaces エントリがありません（追加するには /configure:claude-plugins --fix を実行してください）

検証または修正スクリプト用の jq 参照スニペット：

MP_KEY=$(jq -r '.extraKnownMarketplaces // {} | to_entries | map(select(.value.source.repo == "laurigates/claude-plugins")) | .[0].key // empty' .claude/settings.json)
if [ -z "$MP_KEY" ]; then
  echo "ERROR: no extraKnownMarketplaces entry with source.repo = laurigates/claude-plugins"
else
  jq -e --arg k "@$MP_KEY" '.enabledPlugins // {} | to_entries | map(select(.key | endswith($k))) | length > 0' .claude/settings.json >/dev/null \
    && echo "OK: marketplace enrolled as $MP_KEY with enabled plugins" \
    || echo "WARN: marketplace $MP_KEY enrolled but no @${MP_KEY} entries in enabledPlugins"
fi

ステップ 2：スコープ固有の監査を実行する

--scope=registry または all の場合：

bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/check-registry.sh" \
  --home-dir "$HOME" --project-dir "$(pwd)"

STATUS=、PLUGIN_COUNT=、ORPHANED_ENTRIES=、STALE_ENABLED_ENTRIES=、および ISSUES: を解析します。

--scope=stack または all の場合：内部の health-audit スキルの技術スタック監査手順に従います（${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md およびその REFERENCE.md を参照）。

--scope=agentic または all の場合：内部の health-agentic-audit スキルのスキル品質監査手順に従います（${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md およびその REFERENCE.md を参照）。

--scope=runtime または all の場合：

bash "${CLAUDE_SKILL_DIR}/scripts/check-runtime.sh" --home-dir "$HOME" --project-dir "$(pwd)"

STATUS=、RUNTIME_SIZE_BYTES=、PROJECTS_TOTAL=、PROJECTS_DEAD=、GH_PATHS_TOTAL=、GH_PATHS_DEAD=、ORPHAN_DISABLED_MCP=、DUPLICATE_MCP=、CLEANUP_SUGGESTED=、および ISSUES: を解析します。すべてのデッドパス／孤立したサーバーを一覧表示するには --verbose を指定します（デフォルトでは出力を簡潔に保つため、カテゴリごとに問題をまとめて 1 件だけ表示します）。

runtime スコープでは ~/.claude.json を監査します。これは、セッションのたびに肥大化し、自動的に整理されることのないハーネス状態ファイルです。次の 4 種類の肥大化を報告します：デッド状態の projects[] キー、デッド状態の githubRepoPaths[*] ワークツリーパス、孤立した disabledMcpServers[] エントリ、ベア形式と名前空間付き形式で重複している MCP 名。監査は読み取り専用です。ほかの Claude Code セッションを終了した後、オペレーターが手動で実行するための jq フィルターを提案として出力します。

同時書き込みに関する警告。 ハーネスはセッション終了時に ~/.claude.json を書き換えます。監査で提案されたクリーンアップを適用する前に、ほかの Claude Code セッションをすべて終了してください。終了しないと、実行中のセッションが次にファイルを書き込む際に、メモリー上の状態で編集内容が上書きされます。自動クリーンアップ用の書き込み機能は、この監査の対象外です。

--scope=usage または all の場合：

bash "${CLAUDE_SKILL_DIR}/scripts/check-usage.sh" --home-dir "$HOME" --project-dir "$(pwd)"

STATUS=、HISTORY_AVAILABLE=、TRANSCRIPTS_SCANNED=、SKILLS_ENABLED=、SKILLS_FIRED=、SKILLS_NEVER_FIRED=、SKILLS_DORMANT=、AGENTS_ENABLED=、AGENTS_FIRED=、AGENTS_NEVER_FIRED=、AGENTS_DORMANT=、SCHEMA_DRIFT_SUSPECTED=、および ISSUES: を解析します。発火したことのない／休眠状態のスキルとエージェントをすべて一覧表示するには --verbose を指定します（デフォルトでは各カテゴリを 1 行の問題にまとめます）。休眠と判定するしきい値を変更するには --window-days N を指定します（デフォルトは 30 です）。

usage スコープでは、ローカルのセッショントランスクリプト（~/.claude/projects/*/*.jsonl）を分析し、スキルとエージェントが最後に呼び出された時期を調べます。一度も発火していないスキル／エージェント（インストール済みだが、履歴内で一度も呼び出されていないもの）と、休眠状態のスキル／エージェント（最後の呼び出しから指定期間が経過したもの）を特定します。エージェントの呼び出しは、subagent_type をキーとする Agent／Task の tool_use イベントから読み取ります。検出結果は削除対象の一覧ではなく、確認を推奨する候補です。スキルやエージェントは、必要になる頻度が低くても適切な場合があります（復旧、移行、親スキルによって起動が制御されるオンデマンドのサブエージェントなど）。監査は読み取り専用です（--fix による処理経路はありません）。

このスコープは ~/.claude.json の pluginUsage.usageCount を読み取りません。また、読み取りを開始してはなりません。 このカウンターはスキル／エージェント／コマンドの提供数と同じ数だけフックの発火回数を集計するため、使用状況ではなくフックの起動頻度でプラグインを順位付けします。詳しくは .claude/rules/plugin-usage-telemetry.md を参照してください。提供状況のシグナルとなるのはトランスクリプト分析です。runtime スコープが ~/.claude.json を使うのはこれとは無関係で、ファイルの肥大化のみを調べます。

ローカル環境向けです。 セッション履歴はローカルに保存され、長期間残るため、このスコープはリモート／Web サンドボックスではほとんど役に立ちません（新しくクローンした環境にはトランスクリプトが 1 件以下しかありません）。トランスクリプトが 2 件未満の場合、すべてのスキルを一度も発火していないと報告するのではなく、STATUS=SKIP と HISTORY_AVAILABLE=false を出力します。TRANSCRIPTS_SCANNED>0 でもツール呼び出しを 1 件も解析できない場合は、誤ってすべてが一度も発火していないと判定せず、STATUS=WARN TYPE=schema_drift（トランスクリプトの JSON 形式が変更されたこと）を出力します。

ステップ 3：検出結果を報告する

スコープごとにまとめたレポートを出力します。

1. 環境 — プラグイン／設定／フック／MCP の状態と件数、SessionStart のスモークテスト、pre-commit の妥当性、権限の網羅状況、マーケットプレイスへの登録
2. レジストリ — 孤立した projectPath エントリ、古い enabledPlugins キー、レジストリと設定の不整合
3. スタック — 検出されたスタックと、関連／無関係／不足しているプラグインの推奨事項
4. エージェント — 最適化テーブルがないスキル、単独の CLI コマンド、古いレビュー
5. ランタイム — ~/.claude.json のサイズ、使用されていないプロジェクト／githubRepoPaths、孤立した disabledMcpServers、重複した MCP の命名（読み取り専用 — --fix の経路なし）
6. 使用状況 — セッションテレメトリに基づく、一度も呼び出されていないスキルと休眠中のスキル（読み取り専用 — --fix の経路なし。不十分な履歴は SKIP）

スコープごとの STATUS= インジケーター（OK/WARN/ERROR）と問題件数を使用します。以下のサマリーテーブルを含めてください。

チェック	ステータス	問題
プラグインレジストリ	OK/WARN/ERROR	...
設定ファイル	OK/WARN/ERROR	...
フックの設定	OK/WARN/ERROR	...
MCP サーバー	OK/WARN/ERROR	...
SessionStart スモークテスト	OK/WARN/ERROR	...
Pre-commit 設定	OK/WARN/ERROR/SKIP	...
権限の網羅状況	OK/WARN/ERROR	...
マーケットプレイスへの登録	OK/WARN/ERROR	...
レジストリ監査	OK/WARN/ERROR	...
スタック監査	OK/WARN/ERROR	...
エージェント監査	OK/WARN/ERROR	...
ランタイム監査	OK/WARN/ERROR	...
使用状況監査	OK/WARN/ERROR/SKIP	...

レポートテンプレートの全文は REFERENCE.md を参照してください。

ステップ 4：修正を適用する（--fix を指定した場合）

--fix が指定されている場合：

1. --scope=all が指定され、複数のスコープで問題が見つかった場合は、AskUserQuestion を使用して修正するスコープをユーザーに選択してもらいます（複数選択：registry、stack、agentic）。

2. 選択したスコープごとに、次の処理を委任します。

   スコープ	委任先
   registry	bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)"（指定されている場合は --dry-run を渡します）
   stack	${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md（ステップ 6）の --fix フローに従います
   agentic	${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md（ステップ 6）の --fix フローに従います

3. 各スクリプトの出力（STATUS=、REMOVED_COUNT=、MESSAGE=、RESTART_REQUIRED=）を解析し、変更内容を報告します。

4. いずれかの修正で RESTART_REQUIRED=true が報告された場合は、Claude Code を再起動するようユーザーに伝えます。

ステップ 5：検証する

該当するチェックを再実行し、問題件数が減少したことを確認します。

エージェント最適化

コンテキスト	コマンド
全スキャン	/health:check
レジストリのみ	/health:check --scope=registry
スタックの関連性のみ	/health:check --scope=stack
エージェント監査のみ	/health:check --scope=agentic
ランタイム状態の監査（~/.claude.json）	/health:check --scope=runtime
使用状況テレメトリ（未呼び出し／休眠中のスキル）	/health:check --scope=usage
カスタム休眠期間で使用状況を確認	bash check-usage.sh --window-days 60 --verbose
すべて修正（対話形式）	/health:check --fix
修正内容のドライランプレビュー	/health:check --fix --dry-run
詳細な診断	/health:check --verbose
プラグインレジストリの存在を確認	find ~/.claude/plugins -name 'installed_plugins.json'
設定 JSON を検証	find .claude -maxdepth 1 -name 'settings.json'
インストールスクリプトをスモークテスト	CLAUDE_CODE_REMOTE=true bash scripts/install_pkgs.sh
pre-commit 設定を検証	pre-commit validate-config .pre-commit-config.yaml
マーケットプレイスへの登録を確認	find .claude -maxdepth 1 -name 'settings.json' を実行し、次に extraKnownMarketplaces を grep します

既知の問題

問題	症状	修正方法
#14202	プラグインが「インストール済み」と表示されるが、有効ではない	/health:check --scope=registry --fix
settings.json の古い enabledPlugins キー	プラグインが有効と表示されるが、レジストリ／マーケットプレイスのエントリがない	/health:check --scope=registry --fix
孤立した projectPath	削除済みプロジェクト用にプラグインがインストールされている	/health:check --scope=registry --fix
settings JSON が無効	設定ファイルを読み込めない	/health:check
マーケットプレイスへの登録漏れ	laurigates/claude-plugins のスキルをウェブセッションで利用できない	/configure:claude-plugins --fix