メインコンテンツへスキップ
AMPL/ dev
開発系講座一覧

呼ばれない、読まれない、ぶつかる、途中で失敗する

スキルを作っても、思ったとおりに動かないことがあります。/context・/skills・/doctorで何が読み込まれているかを確かめ、4つの症状ごとに原因を切り分ける手順を扱います

このレッスンで

終わる頃には、次ができるようになります

  • /context・/skills・/doctorを使って、スキルが実際に読み込まれているかを確認できる
  • 呼ばれない・読まれない・ぶつかる・途中で失敗するの4症状を、それぞれ別の原因として切り分けられる
  • SKILL.mdを編集したときに再起動が必要な場合と不要な場合を区別できる

これまでのレッスンで、スキルの候補を選び、descriptionを書き、ファイル構成を整え、道具を絞り、共有の経路まで決めました。最後に扱うのは、それでも思ったとおりに動かないときの直し方です。


まず、何が読み込まれているかを見る

原因を推測する前に、Claude Codeが実際に何を読み込んでいるかを確認します。公式ドキュメントによれば、/contextはそのセッションで読み込まれているものすべて(スキルを含む)を一覧できるコマンドです。組み込みで最初から使える「bundled skills」は/contextには表示されますが、/skillsの一覧には出ない点も覚えておいてください。プロジェクト・個人用・プラグインそれぞれのスキルを一覧したいときは/skillsを使います。まずこの2つのコマンドで、そもそもスキルが存在として認識されているかを確認するのが、診断の出発点です。


症状ごとの原因

症状は大きく4つに分かれます。それぞれ原因が違うので、順番に切り分けます。

呼ばれない(/skillsには出るのにClaudeが自分から使わない)

frontmatterの`disable-model-invocation: true`が原因か、descriptionが実際の頼み方と噛み合っていない。/skillsの「user-only」バッジで判定できる

読まれない(/skillsに出てこない)

`.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で問題が消えるなら、原因はこれらのどれかにあると分かります。

途中で失敗するときの切り分け手順

1

/context・/skillsで状態確認

そもそもスキルが読み込まれているか、意図したファイルかを確認する

2

claude --safe-modeで切り分け

問題が消えるなら、原因はCLAUDE.md・スキル・プラグイン・フック・MCPのどれかにある

3

claude doctor / /doctorで設定を点検

設定ファイルの不備を診断し、/doctorでは修正案の提示と実行前の確認もできる

claude doctorはターミナルから実行でき、インストールと設定の読み取り専用の診断を出力します。セッション内で使う/doctorは、さらに修正案を提示し、実行前に確認を挟んでくれます。


やってみよう

演習1:自分のスキルで4症状のどれが起きそうか予想する

これまで考えてきたスキル候補について、4つの症状のうちどれが起きそうか、理由とあわせて予想してみましょう。descriptionの書き方、ファイルの置き場所、同名スキルの有無など、これまでのレッスンで扱った内容を振り返ってください。

演習2:確認する順番を書き出す

予想した症状について、/context・/skills・claude --safe-mode・/doctorのうち、どれをどの順番で確認するかを書き出してみてください。


これでこのコースは終わりです。候補を選び、descriptionを磨き、ファイルを組み立て、道具を絞り、共有し、動かないときの直し方まで、スキルを作る一連の実務を一通り扱いました。

参考

Claude Code 公式: Debug your configuration
/context・/skills・/doctor・claude --safe-modeなど、設定が反映されないときの診断コマンド一式についての一次情報
code.claude.com/docs · code.claude.com
Claude Code 公式: Extend Claude with skills(Resolve skills that share a name)
同名スキルの優先順位(エンタープライズ>個人用>プロジェクト)と、ライブ変更検出の仕組み
code.claude.com/docs · code.claude.com
Claude Academy: エージェントスキル入門
このコースの考え方の出どころになったAcademyコース。事実の裏取りは公式ドキュメントで別途行っています
academy.claude.com · academy.claude.com

このレッスンは役に立ちましたか?