スキルのトラブルシューティング
スキルのトラブルシューティング · 4 min
スキルが期待どおりに動作しない場合、問題は通常いくつかの予測可能なカテゴリーに
分類されます。この動画では、トリガーされないスキルから優先順位の競合、実行時の
失敗まで、それぞれのケースを順に取り上げ、体系的なトラブルシューティングの進め方
を紹介します。また、スキルバリデーターツールと、読み込みの問題を診断するための
claude --debug の使い方についても学びます。
重要なポイント
- まずはスキルバリデーターツールから始めましょう。これを使えば、他の問題のデバッグに時間を費やす前に構造上の問題を検出できます
- スキルがトリガーされない場合、原因はほぼ常に記述(description)にあります。実際にリクエストを表現する際の言い回しに合うトリガーフレーズを追加しましょう
- スキルが読み込まれない場合は、
SKILL.mdがスキルのルートではなく名前付きディレクトリの中にあること、そしてファイル名が正確にSKILL.mdであることを確認してください - 誤ったスキルが使われる場合は、記述(description)が似すぎています。もっと明確に区別できるようにしましょう
- 実行時エラーについては、依存関係、ファイル権限(
chmod +x)、パス区切り文字(どこでもスラッシュを使用すること)を確認してください
スキルがうまく動作しない場合、問題は通常、トリガーされない、読み込まれない、競合がある、実行時に失敗する、のいずれかのカテゴリーに分類されます。幸いなことに、ほとんどの修正方法はかなり単純です。
スキルバリデーターを使う
最初に試すべきことは claude plugin validate コマンドです。シェルで、個人用スキルの場合は claude plugin validate ~/.claude/skills、プロジェクトスキルの場合は claude plugin validate .claude/skills を実行してください。Claude Code v2.1.233 以降が必要です。
バリデーターは、フロントマターが正しく解析できない SKILL.md ファイルを検出します。そのため、他の問題のデバッグに時間を費やす前にその問題を発見できます。上記の動画では、uv でインストールする別の検証ツールが紹介されています。
スキルがトリガーされない
スキルは存在し、検証にも通っているのに、期待したときにClaudeがそれを使ってくれない。原因はほぼ常に記述(description)にあります。
Claudeはセマンティックマッチングを使用するため、あなたのリクエストが記述の意味と重なっている必要があります。重なりが十分でなければ、マッチしません。次のことを試してください。
- 実際にリクエストをどう表現しているかと、記述を照らし合わせて確認する
- ユーザーが実際に言いそうなトリガーフレーズを追加する
- 「これをプロファイルして」「なぜこれは遅いの?」「これをもっと速くして」のようなバリエーションでテストする
- いずれかのバリエーションでトリガーされない場合は、そのキーワードを記述に追加する
スキルが読み込まれない
Claudeに「どんなスキルが使えるか」と尋ねてもスキルが表示されない場合は、次の構造上の要件を確認してください。
SKILL.mdファイルは、スキルのルートではなく、名前付きディレクトリの中になければなりません- ファイル名は正確に
SKILL.mdでなければなりません。「SKILL」はすべて大文字、「md」は小文字です
claude --debug を実行して、読み込みエラーを確認してください。自分のスキル名に言及しているメッセージを探しましょう。これだけで問題の原因が直接わかることもあります。
誤ったスキルが使われる
Claudeが誤ったスキルを使ったり、スキル同士を混同しているように見える場合、記述(description)が似すぎている可能性が高いです。明確に区別できるようにしましょう。できる限り具体的にすることは、Claudeがいつそのスキルを使うべきかを判断する助けになるだけでなく、似たような名前の他のスキルとの競合も防いでくれます。
スキルの優先順位の競合
個人用スキルが無視されている場合、エンタープライズまたはより優先順位の高いスキルが同じ名前を持っている可能性があります。

例えば、エンタープライズの「code-review」スキルがあり、あなたも個人用の「code-review」スキルを持っている場合、エンタープライズのものが常に優先されます。選択肢は次のとおりです。
- スキルの名前をもっと明確に区別できるものに変更する(通常はこちらの方が簡単です)
- エンタープライズスキルについて管理者に相談する
プラグインのスキルが表示されない
プラグインをインストールしたのに、そのスキルが見当たりませんか? /plugin を実行し、Installed の下にそのプラグインが表示され、有効になっているかを確認してから、Errors タブを確認してください。このセッション中にインストールした場合は、/reload-plugins を実行してください。
それでもスキルが表示されない場合は、プラグインの構造が間違っている可能性があります。スキルは .claude-plugin/ の中ではなく、プラグインのルートにある skills/ ディレクトリから読み込まれます。シェルで、プラグインのディレクトリに対して claude plugin validate を実行し、マニフェストと各スキルのフロントマターを確認してください。
実行時エラー
スキルは読み込まれるものの、実行中に失敗する。よくある原因はいくつかあります。
- 依存関係の欠落: スキルが外部パッケージを使用する場合、それらはインストールされている必要があります。Claudeが何が必要かを把握できるよう、スキルの記述に依存関係の情報を追加してください。
- 権限の問題: スクリプトには実行権限が必要です。スキルが参照するスクリプトに対して
chmod +xを実行してください。 - パス区切り文字: Windowsであっても、どこでもスラッシュを使用してください。
クイック トラブルシューティング チェックリスト
- トリガーされない? 記述を改善し、トリガーフレーズを追加する。
- 読み込まれない? パス、ファイル名、YAML構文を確認する。
- 誤ったスキルが使われる? 記述同士をもっと明確に区別する。
- 隠れてしまっている? 優先順位階層を確認し、必要なら名前を変更する。
- プラグインのスキルが見当たらない?
/pluginでエラーを確認し、/reload-pluginsを実行する。 - 実行時に失敗する? 依存関係、権限、パスを確認する。
レッスンの振り返り
- これまでの業務で、こうしたトラブルシューティングのシナリオに遭遇したことはありますか? どの修正方法が最も時間の節約になったでしょうか?
- チームとスキルを共有する前に検証するプロセスを、どのように構築しますか?
コースのまとめ
「Introduction to Agent Skills」の修了、おめでとうございます! Claude Codeでスキルを作成、設定、共有、トラブルシューティングする方法を学びました。自分のワークフロー向けにスキルを構築し始める際は、最良のスキルは実際の困りごとから生まれることを忘れないでください。自分が最も頻繁に繰り返している指示から始めてみましょう。