スキルが動かないときの失敗パターン

結論

スキルが動かないとき、原因のほとんどは「読み込まれていない」か「説明文が合っていない」のどちらかです。切り分けの順番さえ決めておけば、書き直しに時間を溶かさずに済みます。逆に呼んでいないのに動く場合も、直す場所は同じ説明文です。

まず「見えているか」を確かめる

書き方を疑う前に、そのスキルがClaude Codeに認識されているかを見ます。設定が効かないときの原因は、たいてい「ファイルが読み込まれていない」「思っていたのと違う場所から読み込まれた」「別のファイルに上書きされた」のいずれかだと公式ドキュメントは説明しています。

確認に使えるものが2つあります。/skillsは、プロジェクト・個人・プラグインの各所から読み込まれたスキルの一覧です。/contextは、いま何がコンテキストを占めているかを分類別に見せます。スキルの説明文がそこに載っていなければ、そもそも候補に入っていません。

発動しないときに見る4点

一覧に出ているのに使われない場合、公式ドキュメントは次の確認を挙げています。

1. 説明文に、利用者が自然に口にする言葉が入っているか
2. What skills are available?と尋ねて、そのスキルが挙がるか
3. 頼み方を、説明文の言葉に寄せて言い直してみる
4. 自分から呼べる設定なら、/スキル名で直接呼んでみる

見落としやすいのがフロントマターの書式エラーです。YAMLが壊れていると、Claude Codeは中身だけを空の設定として読み込みます。この状態でも/スキル名では動くのに、説明文がないためClaudeの側からは選ばれません。「手動なら動くが自動では動かない」ときは、まずここを疑ってください。原因は--debugを付けて起動すると解析エラーとして表示されます。

スキルが多すぎて説明文が削られる

数を増やしたときに起きる問題もあります。Claude Codeは、スキル名と説明文の一覧をコンテキストに読み込みますが、この一覧には文字数の枠があります。枠を超えると、使う頻度の低いものから説明文が落とされます。名前は残るため一覧にはあるのに、判断材料の説明文だけが消えるという状態。

/doctorを実行すると、この一覧がどれだけコンテキストを使っているか、内訳の上位が何かを見られます。心当たりがあるときは確認してください。

逆に、呼んでいないのに動く

意図せず発動する場合の対処は2つです。1つは説明文をより限定的にすること。もう1つはdisable-model-invocation: trueを足して、自分が呼んだときだけ動くようにすることです。

user-invocable: falseは似て非なる設定なので、間違えないでください。こちらはClaudeだけが使える状態にして、/のメニューから隠すためのものです。自動発動を止めたいときに使うと、逆の結果になります。

「効かなくなった」と感じるとき

呼び出したスキルの内容は、そのセッションの会話に残り続けます。最初の返答のあとで効き目が薄れたように感じても、たいていは内容が消えたのではなく、Claudeが別のやり方を選んでいるだけです。この場合は説明文と指示を強め、それでも徹底させたい決まりごとは、スキルではなくHooksのような仕組みで縛る方が確実だと案内されています。

学習上の注意

スキルが動かない原因を、書いた内容の良し悪しだけに求めないでください。読み込まれているか、説明文が届いているか、という配線の問題が先に来ます。順番を決めて切り分ければ、直す場所は自然に絞られます。

なお、動作を試すときは、実際のファイルを書き換えるスキルをいきなり本番のプロジェクトで走らせないでください。手元で試せる小さな場所を用意してから確かめる方が安全です。