ホーム / 全スキル / ワークフロー＆基本ツール / claude-skills-troubleshooting
English (EN)简体中文 (ZH)日本語 (JA)
ワークフロー＆基本ツール · daymade/claude-code-skills

claude-skills-troubleshooting

Claude Code のプラグインおよびスキルの問題を診断・解決します。プラグインをインストールしたものの利用可能なスキル一覧に表示されない場合、スキルが期待通りに起動しない場合、または settings.json 内の enabledPlugins 設定をトラブルシューティングする場合に使用します。トリガーワードには「plugin not working」「skill not showing」「installed but disabled」「enabledPlugins」などが含まれます。

L4 高権限 · 段階的認可と監査V1 コミット固定コマンド実行ネットワーク通信ファイル書き込みDual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE：Copyright (c) 2025 daymade；GitHub API spdx MIT）Commit d5c4678cb5
管理レベルは Skill の能力と推奨統制措置を示すものであり、品質や安全性の認証、利用可否の判定ではありません。使用の可否はユーザーおよび管理者が決定します。Agent 環境によって制約が異なるため、自動保護を仮定しないでください。第三者製 Skill の著作権は原著作者に帰属し、利用リスクは利用者が負います。

1仕組みと動作原理

まず診断スクリプトを実行して機械的切り分けを実施：diagnose_plugins.py がローカルの ~/.claude プラグイン状態ファイル（installed_plugins.json、settings.json の enabledPlugins、known_marketplaces.json）を読み取り、「インストール済みだが未有効化」のリストを照合してキャッシュの鮮度をチェック。

daymade-claude-code/claude-skills-troubleshooting/SKILL.md
Run the diagnostic script to identify common issues: ```bash python3 scripts/diagnose_plugins.py
スクリプトは読み取り専用で書き込みは行わない：3つの設定ファイルを json.load した後に検出結果を出力。終了コードはセマンティック（問題検出時は return 1）。

診断の核心的判断基準：cache ディレクトリの mtime は信用せず、known_marketplaces.json の lastUpdated を鮮度の唯一の情報源とする（タイムゾーン付き ISO-8601 を厳格パースし、欠落・不正形式・タイムゾーンなし・未来のタイムスタンプはすべて無効と判定）。

daymade-claude-code/claude-skills-troubleshooting/scripts/diagnose_plugins.py
never guess freshness from the unreliable cache-directory mtime.
パースには正規表現を用い、タイムゾーンを Z または ±HH:MM に限定して UTC に正規化。STALE_AFTER=7 日を超えた場合は stale、未来のタイムスタンプは invalid と判定。

2層の修復パス：公式 CLI（claude plugin enable/disable/update）と settings.json の enabledPlugins 直接編集を提供。さらに、一括有効化スクリプト enable_all_plugins.py（マーケットプレイス接尾辞でのマッチング、書き込み前に対話的確認を実施）も提供。

daymade-claude-code/claude-skills-troubleshooting/SKILL.md
claude plugin enable plugin-name@marketplace-name
一括スクリプト enable_all_plugins.py：installed_plugins.json と settings.json を読み込み、有効化対象をリスト表示した上で、input('[y/N]') による確認を経て enabledPlugins[k]=true を書き戻す。

ナレッジベースによる裏付け：references/architecture.md でプラグインのライフサイクルとアクティベーションフロー（インストール → キャッシュへコピー → 登録 → 手動有効化 → 起動時の enabledPlugins 読み込み）を解説、references/known_issues.md で上流 GitHub の issue（#17832 など）を追跡、SKILL.md に 4 つの Common Issues の根本原因と解決策を内包。

daymade-claude-code/claude-skills-troubleshooting/references/known_issues.md
https://github.com/anthropics/claude-code/issues/17832
Issue #17832（インストールしても自動有効化されない）は Issue 1 の根本原因の直接的根拠。known_issues.md には #19696/#17089/#13543/#16260 も収録。

「Skill と Command の2系統の拡張」に関するアーキテクチャの明確化：skills/ は説明文に基づき自動マッチングで起動、commands/ は /command-name での明示的呼び出しが必要。明示的に呼び出したい場合は command ファイルの追加が必要。

daymade-claude-code/claude-skills-troubleshooting/SKILL.md
If a skill should be explicitly invocable, add a corresponding command file.
これは「スキルをインストールしたのにトリガーされない」問題を調査する際の重要な切り分け分岐。スキルが Skill ツールで確認できるがマッチしないケースと、そもそも有効化されていないケースは別問題。

2コア機能

01installed と enabled の不整合を機械的に診断（インストール済みかつ未有効化のプラグインをリストアップし、enable コマンドを提示）
02マーケットプレイスキャッシュの鮮度チェック：lastUpdated の検証（タイムゾーン／未来時刻／欠落の検証）＋ 7日間の有効期限判定 ＋ 非ゼロ終了コード
03特定マーケットプレイスのインストール済み未有効化プラグインの一括有効化（書き込み前の y/N 確認付き）
04プラグインアーキテクチャのクイックリファレンス：active 判定（installed_plugins.json への登録 ＋ enabledPlugins=true の2条件）
05skill と command の違いの整理および明示的呼び出しエントリポイント（commands/ ファイル）の案内
06上流 issue の追跡および関連ドキュメントのインデックス（known_issues.md / architecture.md）

3外部依存関係

KindDependency / Endpoint
clipython3
cliclaude（官方 CLI：plugin enable/disable/install/uninstall/marketplace update）
clijq（诊断命令参考中读 JSON）
networkGitHub（issue 引用与 marketplace 内容源）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
  • scripts/: ローカルスクリプトまたはコマンドの実行: scripts/diagnose_plugins.py
  • 网络端点: 外部ネットワークアクセスの宣言: （SKILL が案内するユーザー操作）claude plugin marketplace update —— 公式 CLI による登録済みマーケットプレイスからの取得
  • 本地工作目录: ファイル読み書きおよびアーティファクト出力: ~/.claude/settings.json の enabledPlugins（enable_all_plugins.py での対話的確認後のみファイル全体を書き戻し）
監査ノート： 同梱スクリプトは完全にローカルで動作：diagnose は ~/.claude 配下の3つの設定ファイルを読み取るのみ。enable_all は対話的確認（y/N）後に settings.json の enabledPlugins に書き込みを実施。当該ファイルに平文の環境トークン等が含まれている場合、読み取り・変更・書き戻しに伴い秘密情報を含むファイルに触れることになります（接触面は存在するものの、スクリプトが秘密情報フィールドを処理することはありません）。SKILL が案内する修復手順には公式 claude CLI によるマーケットプレイス更新（登録済みマーケットプレイス/GitHub への外部送信、対象は想定可能）およびキャッシュディレクトリの削除（rm -rf、ユーザーによる手動実行、再構築可能）が含まれます。また、ドキュメントには GitHub issue へのリンクも記載されています。独自実装のネットワークコードや認証情報の抽出ロジックは一切含まれていません。

5二重目の独立検証

  • [ok] 无网络外发（脚本层） — 两脚本零网络；https 只出现在 SKILL/known_issues 文档链接
  • [ok] diagnose 只读声明属实 — 全文仅 json.load + print，无写文件路径
  • [ok] enable_all 写前确认属实 — 写入前 input("Enable all these plugins? [y/N] ")，非 y 即取消
  • [ok] lastUpdated 唯一新鲜度来源规则三方一致 — SKILL.md / architecture.md / diagnose_plugins.py 同口径（时区必需、mtime 不可信、7 天过期、未来时间戳无效）
  • [ok] 诊断退出码语义 — main() 末尾 missing/stale/invalid 任一成立打印 Action needed 并 return 1，与 SKILL 'exits nonzero' 一致
  • [ok] settings.json 含密钥时的接触面 — enable_all 整文件 json.load/json.dump 回写；密钥字段原样保留不处理——按统一分档‘接触即 orange’上浮边界，本档定 yellow 因脚本从不读取/传递密钥字段，reason 已注明触发条件

6結論

  • 機械的診断の先行 ＋ 明確な根本原因特定（公式バグ #17832）により、「インストールしたのに表示されない」問題を推測から検証可能な状態確認へと転換
  • 鮮度判定を lastUpdated（タイムゾーン／未来時刻検証を含む）に厳密固定しており、ディレクトリの mtime を参照するより高信頼
  • 整理された Runbook 構造：Quick Diagnosis → Common Issues → コマンド早見表により、エージェントが症状から直ちに対処へ移行可能
  • 破壊的修復（キャッシュクリア、一括 enable）には確認ステップまたは CLI の公式パスを用意
    • 最適な用途： Claude Code ユーザーが「プラグインをインストールしたのに表示されない／スキルが起動しない／enabledPlugins の設定不備／キャッシュが古い」といった事象の体系的な切り分けを行う場合に最適。また、特定マーケットプレイスの全プラグインを一括有効化（スクリプト＋確認）したいメンテナーや、プラグイン有効化の仕組みを理解したい場合にも適しています。
    不向きな用途： Claude Code のプラグイン機構と無関係な障害（一般的な実行エラー、ネットワーク、権限エラーなど）には不向き。スクリプトを「万能修復ツール」として扱う用途には不向き（診断と一括有効化のみを行い、その他の修復は公式 CLI 手順が必要）。~/.claude 設定が存在しない環境や純粋な Codex 環境での使用には不向き。
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload claude-skills-troubleshooting.tar.gz
    sha256: 3f56dc20d44cb7a1…
    Option B · Copy Guide for Agent
    install.json
    Agent はこの JSON ガイドから自動的にダウンロードして検証します。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.