Skillが動かない時のトラブルシューティング

claude-code 101

Ryo Nakagami

2026年05月02日

Index

学習目標

Skill不調を4カテゴリに切り分けて原因を特定できる
Skills Validatorとclaude --debugで構造・読込み問題を診断できる
description調整・priority整理・runtime修正で復旧できる

対象レベル

Skillを自作・運用しており不具合に遭遇した開発者

前提知識 & 必要環境

Skillの基本構造（SKILL.md・description）を理解している
配布手段（プロジェクト・プラグイン・enterprise）の概要を把握

regmonkey_index:
  title_fontsize: 1.2em
  bullet_fontsize: 1.0em
  children:
    - title: 1. トラブルは4カテゴリ<br>に分かれる
      description:
        - <strong>trigger / load / 重複 / runtime</strong>のどれかに収束する
        - カテゴリを先に当てれば対処手順が一意に決まる
      width: [40, 60]
    - title: 2. Skills Validator<br>から始める
      description:
        - 構造的な問題は<strong>デバッグ前に弾く</strong>のが定石
        - <code>claude --debug</code>で読込みエラーを補完
      width: [40, 60]
    - title: 3. trigger / load / 重複<br>の切り分け
      description:
        - 起動しない・読込まれない・他Skillが選ばれるの3症状
        - 大半は<strong>descriptionの書き方</strong>に帰着する
      width: [40, 60]
    - title: 4. Priorityとプラグイン特有<br>の症状
      description:
        - enterprise > project > personalの<strong>優先順位</strong>で上書きされる
        - プラグインSkillはcache再構築で復活することが多い
      width: [40, 60]
    - title: 5. Runtime errorsの<br>3点チェック
      description:
        - <strong>依存・実行権限・パス区切り</strong>を順に確認
        - SKILL.md冒頭にdependency情報を明記
      width: [40, 60]

トラブル分類とSkills Validator

トラブル分類とSkills Validator
trigger / load / 重複の切り分け
Priorityとプラグイン特有の症状
Runtime errorsの3点チェック

Skill不調は4カテゴリのいずれかに収束する

「動かない」を漠然と探さず，trigger / load / 重複 / runtimeのどれかに当てはめる

切り分けの基本姿勢

症状を4カテゴリのどれかに当てはめてから対処に進む：カテゴリが決まれば手順は一意
「動かない」「効かない」のような曖昧な記述で深追いしない：まず分類してから具体策へ

Skills Validatorで構造的な問題を先に弾く

descriptionや実行ロジックを疑う前に，構造バリデーションでファイル配置・YAMLを確認する

最初に試すコマンド

agent skills verifier を導入：uv経由のインストールが最短，uv tool install skills-ref
Skillディレクトリ内，もしくは任意の場所から実行できる
ファイル名・配置・YAML構造などの機械的に検出可能な不備を先にすべて潰す

validate コマンドの実行例

$ agentskills validate ./.claude/skills/regmonkey-slide-skill
Valid skill: .claude/skills/regmonkey-slide-skill

agentskills validate <skillパス> で実行：成功時は Valid skill: <パス> のみ出力
構造OKでも動かない場合は claude --debug でSkill名を含むエラー行を探し，trigger / load / 重複 / runtimeの切り分けに進む

trigger / load / 重複の切り分け

トラブル分類とSkills Validator
trigger / load / 重複の切り分け
Priorityとプラグイン特有の症状
Runtime errorsの3点チェック

Skillがtriggerしない時はdescriptionを疑う

Skill選択 = 依頼文とdescriptionの意味マッチ．重なりが薄いと発火しない

descriptionとユーザ語彙のズレを見直す

自分が実際に発する依頼の言い回しとdescriptionが意味的に重なっているか確認する
ユーザが口にしそうなトリガーフレーズをdescriptionに足す
help me profile this / why is this slow? / make this faster 等のバリエーションでテストする
発火しなかった表現のキーワードを追記してセマンティックマッチの当たりを広げる

NGパターン

description が抽象的・自己満足的：「コード品質を高めるSkill」だけだとマッチしない
動詞・対象・状況を含めて書き直す：「Pythonのプロファイリングを実施し，遅い処理を特定する」のように具体化

Skillがloadしない時はSKILL.mdの構造を疑う

claude の一覧に出てこない = Skillは読み込まれていない．配置とファイル名から確認する

Skill読込み時の必須要件

SKILL.md は名前付きディレクトリの中に置く：skillsルート直下に置いてはいけない
ファイル名は厳密に SKILL.md：SKILL 大文字・md 小文字を守る
claude --debug で読込みエラーを表示し，Skill名を含むメッセージを確認する

正しい配置例

.claude/skills/
├── code-review/
│   └── SKILL.md         ← OK：名前付きディレクトリ + 正確なファイル名
└── SKILL.md             ← NG：skillsルート直下に置かれている

違うSkillが選ばれる時はdescriptionの差別化

Claudeが似たSkillを取り違える，あるいは混乱する場合，description同士の意味が近すぎる

descriptionは独立性を高める

各Skillのdescriptionを互いに差別化：守備範囲・対象・タイミングを書き分ける
「具体的に書く」ことは選ばれやすさ + 取り違え防止の両方に効く
似た名前のSkillが既にある場合，差別化に失敗するとどちらか一方が常に勝つ

書き分けの観点

対象範囲：「Pythonコード全般」 vs 「Pandasデータフレーム操作」
起動タイミング：「PR作成時のレビュー」 vs 「実装中のリファクタ提案」
期待出力：「指摘リスト」 vs 「修正案を含む差分」

Priorityとプラグイン特有の症状

トラブル分類とSkills Validator
trigger / load / 重複の切り分け
Priorityとプラグイン特有の症状
Runtime errorsの3点チェック

上位スコープのSkillに名前が衝突すると常に負ける

個人Skillが無視される場合，同名のenterprise Skillが優先されているのが定番パターン

Skill priorityの基本ルール

同名Skillが複数スコープに存在する場合，enterprise > project > personalの順で優先される
「enterpriseのcode-review」と「個人のcode-review」が並ぶと，enterprise側が必ず勝つ
自分のSkillが反応しない時はまず同名Skillの存在を疑う

対処の選択肢

Skill名を変更してより独自性の高い名前にする：実務上はこれが最短
組織管理者にenterprise Skillの仕様・上書き可否について相談する
役割が同じなら統合，異なるなら名前で機能差を表現し直す

プラグインSkillが現れない時はキャッシュを疑う

インストール直後の不具合は環境状態の問題が多い．構造の問題はvalidatorで弾く

復旧手順は3ステップ固定

キャッシュをクリアする : rm ~/.claude/plugins/cache
Claude Codeを再起動する
該当プラグインを再インストールする

それでも見えない場合

プラグイン側の構造に不備がある可能性が高い：Skills Validatorの本領が活きる場面
プラグインのskills/ディレクトリ配下に，個別SkillがSKILL.mdを持つフォルダで分かれているか確認する

Runtime errorsの3点チェック

トラブル分類とSkills Validator
trigger / load / 重複の切り分け
Priorityとプラグイン特有の症状
Runtime errorsの3点チェック

Runtime失敗は依存・権限・パスの3点で決まる

依存

Missing dependencies

外部パッケージ未インストールで失敗
description冒頭に必要パッケージを明記
Claudeが事前に必要環境を判断できる

権限

Permission issues

スクリプトに実行権限がない
chmod +x を全スクリプトに適用
Skillが参照する全ファイルが対象

パス

Path separators

Windowsでもforward slashを使う
バックスラッシュは互換性問題の温床
Skill内のパス記述すべてに適用

Quick Troubleshooting Checklist

record1:
  category: triggerしない
  rule:
    - <span class="regmonkey-bold">descriptionとユーザ語彙のズレ</span>が原因のほぼ全て
  actions:
    - 実際の依頼フレーズをdescriptionに反映
    - トリガーフレーズ・キーワードを追加
    - バリエーションでテストし発火を確認

record2:
  category: loadしない
  rule:
    - <span class="regmonkey-bold">配置・ファイル名・YAML</span>のいずれかが破綻
  actions:
    - 名前付きディレクトリ配下に <code>SKILL.md</code> を置く
    - ファイル名を <code>SKILL.md</code> に厳密一致させる
    - <code>claude --debug</code> でSkill名を含む行を確認

record3:
  category: 違うSkillが選ばれる
  rule:
    - description同士の<span class="regmonkey-bold">意味が近すぎる</span>
  actions:
    - 対象範囲・タイミング・出力で書き分ける
    - Skill名と説明から重複を解消
    - 統合可能なら1つにまとめる

record4:
  category: Priorityで負ける
  rule:
    - 上位スコープに<span class="regmonkey-bold">同名Skill</span>が存在
  actions:
    - Skill名を独自性の高い名前に変更
    - 管理者にenterprise Skillの扱いを相談
    - 役割の重複は機能差で名前に表現

record5:
  category: プラグイン未表示
  rule:
    - <span class="regmonkey-bold">キャッシュ・再起動・再インストール</span>で大半復旧
  actions:
    - キャッシュをクリア
    - Claude Codeを再起動
    - プラグインを再インストール．残ればvalidator

record6:
  category: Runtime失敗
  rule:
    - <span class="regmonkey-bold">依存・権限・パス</span>の3点を順に確認
  actions:
    - 必要パッケージをdescriptionに明記
    - <code>chmod +x</code> でスクリプトに実行権限
    - パス区切りは全環境でforward slashに統一