これまでのレッスンで、スキルの候補を選び、descriptionを書き、ファイル構成を整え、道具を絞り、共有の経路まで決めました。最後に扱うのは、それでも思ったとおりに動かないときの直し方です。
まず、何が読み込まれているかを見る
原因を推測する前に、Claude Codeが実際に何を読み込んでいるかを確認します。公式ドキュメントによれば、/contextはそのセッションで読み込まれているものすべて（スキルを含む）を一覧できるコマンドです。組み込みで最初から使える「bundled skills」は/contextには表示されますが、/skillsの一覧には出ない点も覚えておいてください。プロジェクト・個人用・プラグインそれぞれのスキルを一覧したいときは/skillsを使います。まずこの2つのコマンドで、そもそもスキルが存在として認識されているかを確認するのが、診断の出発点です。
症状ごとの原因
症状は大きく4つに分かれます。それぞれ原因が違うので、順番に切り分けます。
frontmatterの`disable-model-invocation: true`が原因か、descriptionが実際の頼み方と噛み合っていない。/skillsの「user-only」バッジで判定できる
`.claude/skills/名前.md`のようにファイル単体で置いていないか確認する。`.claude/skills/名前/SKILL.md`という、フォルダの中にSKILL.mdを置く形が必要
優先順位はエンタープライズ＞個人用＞プロジェクトの順。個人用のスキルが同名のプロジェクトのスキルより先に見つかる、といった状況が起こり得る
スキルそのものが原因かどうかを切り分けるところから始める。次の節で扱う`--safe-mode`と`/doctor`を使う
編集したのに反映されない、は再起動が原因ではない
SKILL.mdを編集したのに変更が反映されない、という相談はよくありますが、原因はほとんどの場合、再起動の有無ではありません。
補足
編集は再起動なしで反映される
Claude Codeの公式ドキュメントによれば、~/.claude/skills/・プロジェクトの.claude/skills/・--add-dirで追加したディレクトリ配下の.claude/skills/は、ファイルの追加・編集・削除がセッション内で数秒以内に反映されます。再起動は不要です。再起動が必要になるのは、セッションを開始した時点では存在しなかった、最上位のスキルフォルダを新規に作った場合だけで、そのときは/reload-skillsを実行します。「編集したら必ず再起動」という説明を見かけることがありますが、公式ドキュメントの現在の記述とは違います。
反映されないときは、まず/skillsで最新の状態が見えているかを確認し、それでも変わらない場合に初めて/reload-skillsを試す、という順番が無駄がありません。
途中で失敗するときの切り分け方
スキルを呼び出したところまでは動くのに、途中でおかしくなる場合は、原因がスキル自体にあるのか、それとも設定全体の別の場所にあるのかを先に切り分けます。
公式ドキュメントは、claude --safe-modeというオプションを紹介しています。これはCLAUDE.md・スキル・プラグイン・フック・MCPサーバー・カスタムコマンドやエージェントをすべて無効にしたセッションを起動する機能で、認証・モデル選択・組み込みツール・権限設定は通常どおり動きます。safe-modeで問題が消えるなら、原因はこれらのどれかにあると分かります。
途中で失敗するときの切り分け手順
/context・/skillsで状態確認
そもそもスキルが読み込まれているか、意図したファイルかを確認する
claude --safe-modeで切り分け
問題が消えるなら、原因はCLAUDE.md・スキル・プラグイン・フック・MCPのどれかにある
claude doctor / /doctorで設定を点検
設定ファイルの不備を診断し、/doctorでは修正案の提示と実行前の確認もできる
claude doctorはターミナルから実行でき、インストールと設定の読み取り専用の診断を出力します。セッション内で使う/doctorは、さらに修正案を提示し、実行前に確認を挟んでくれます。
やってみよう
演習1：自分のスキルで4症状のどれが起きそうか予想する
これまで考えてきたスキル候補について、4つの症状のうちどれが起きそうか、理由とあわせて予想してみましょう。descriptionの書き方、ファイルの置き場所、同名スキルの有無など、これまでのレッスンで扱った内容を振り返ってください。
演習2：確認する順番を書き出す
予想した症状について、/context・/skills・claude --safe-mode・/doctorのうち、どれをどの順番で確認するかを書き出してみてください。
今日のまとめ
3行で振り返ります。
- 診断はまず
/contextと/skillsで、何が実際に読み込まれているかを確認するところから始める - 呼ばれない・読まれない・ぶつかる・途中で失敗するは、それぞれ原因が違う。descriptionの噛み合わせ、フォルダの形、優先順位、設定全体の切り分けと分けて考える
- SKILL.mdの編集は再起動なしで反映される。再起動が要るのは最上位のスキルフォルダを新規に作ったときだけで、そのときは
/reload-skillsを使う
これでこのコースは終わりです。候補を選び、descriptionを磨き、ファイルを組み立て、道具を絞り、共有し、動かないときの直し方まで、スキルを作る一連の実務を一通り扱いました。
セルフチェック
1. スキルが`/skills`には出るのに、Claudeが自分から呼び出してくれないとき、まず疑うべき原因はどれですか。
2. SKILL.mdの本文を編集したとき、Claude Codeの現在の公式ドキュメントに沿った正しい説明はどれですか。
3. スキルの実行中に問題が起きたとき、原因がスキル自体にあるかを切り分けるために本文が紹介した方法はどれですか。