Claude Code Skillsが動かない・発火しない原因9パターンと直し方——公式docsとGitHub Issueで裏取りした
Claude Code Skillsが「一覧に出てこない」「発火しない」「descriptionが消える」「disable-model-invocationで手動呼び出しまで拒否される」等の原因を症状別に整理。未修正のGitHub Issueと公式トラブルシューティングを突き合わせた自己診断表つき。
エンジニアのゆとです。
SKILL.mdを書いて~/.claude/skills/に置いたのに、Claudeが一向にそれを使ってくれない。/skill-nameで直接呼んでも反応がない。あるいは逆に、disable-model-invocation: trueを付けたはずなのにスラッシュコマンドまで拒否される——Claude Code Skillsを触っていると、こういう「設定は合っているはずなのに動かない」場面に必ず一度はぶつかる。
「Claude Code Skills 動かない」で検索すると出てくるのは大半が「Skillsとは何か」「作り方」を説明する記事で、トラブルシューティングに特化したものは日本語ではほぼ見当たらなかった。この記事では公式ドキュメントのトラブルシューティング項目を軸に、実際にAnthropicのGitHub Issueで報告されている未修正バグ・仕様上の落とし穴まで含めて、症状別に原因を整理した。
結論 — 症状別の原因早見表
| 症状 | 原因 | 状態 |
|---|---|---|
スキル一覧（/メニュー）にそもそも出てこない | 配置場所の間違い、ネストディレクトリの仕様誤解 | 仕様どおり（後述の場所を確認） |
settings.jsonのadditionalDirectoriesに置いたのに検出されない | 仕様上の制約。ファイルアクセス許可とスキル読み込みは別物 | 仕様（--add-dirで回避可） |
| Gitワークツリー内でプロジェクトスキルだけ消える | ワークツリーのネスト構造がスキル検出を誤認識していた | 修正済み |
descriptionは正しいのに一部のスキルだけ説明が表示されない | ハーネス側の非決定的なバグ（GitHub Issue #68677） | 未修正（Open） |
| 説明の途中で文字が切れる／リストから消える | スキル一覧の文字数予算オーバー | 仕様（設定で緩和可） |
| 逆に何を聞いても勝手にスキルが発火する | descriptionが抽象的すぎる | 設定ミス |
disable-model-invocation: trueにしたら/skill-nameまで拒否された | フラグの解釈がユーザー呼び出しまで巻き込むバグ | 複数報告あり（重複クローズ） |
skillOverridesで"off"にしたのに呼び出せてしまう | 設定が一覧からの除外に反映されない | 複数報告あり（重複クローズ） |
| SKILL.mdのYAMLフロントマターが壊れている | 気づきにくいサイレント障害 | 設定ミス（--debugで検出可） |
| 会話が長くなると急にスキルの内容を無視し始める | auto-compactionで古いスキルの中身がコンテキストから落ちた | 仕様（再invokeで復元） |
自分の症状がどれに近いか分かったら、該当の見出しまで飛んで構わない。SKILL.mdの書き方そのものから知りたい場合は先にこちらを読んだほうが早い。
ケース1: スキル一覧にそもそも出てこない
一番多いのがこれ。原因はだいたい配置場所の勘違いに集約される。公式ドキュメントが定義している配置場所は4つで、それぞれ影響範囲が違う。
| 場所 | パス | 影響範囲 |
|---|---|---|
| Enterprise | 管理設定経由 | 組織内の全ユーザー |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | すべてのプロジェクト |
| Project | .claude/skills/<skill-name>/SKILL.md | このプロジェクトのみ |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | プラグインが有効な場所 |
見落としがちなのが「ディレクトリ名がそのままコマンド名になる」という仕様。SKILL.mdのfrontmatterにname: my-skillと書いても、.claude/skills/my_skill/SKILL.mdのようにディレクトリ名が違っていれば呼び出しコマンドはディレクトリ名基準になる（プラグインルート直下のSKILL.mdだけは例外で、nameフィールドがそのままコマンド名になる)。ディレクトリ名とnameが食い違っていて「呼んでいるつもりのコマンドが存在しない」というのは実際によくある勘違いだ。
もう一つの盲点が、セッション開始時に存在しなかった最上位のスキルディレクトリは、ファイルの追加・編集をライブ検出してくれても、ディレクトリ自体を新規作成した場合はセッション再起動が必要という仕様。mkdir -p ~/.claude/skills/new-skillした直後に同じセッションで試して「反応しない」と焦る前に、一度Claude Codeを再起動してみるといい。
ケース2: additionalDirectoriesに置いたのに検出されない
settings.jsonのpermissions.additionalDirectoriesにディレクトリを追加すれば、そこにある.claude/skills/も読み込まれると考えるのは自然だが、これは公式に「仕様どおりの制約」として明記されている。
このIssueが報告した挙動差は、その後公式ドキュメントのトラブルシューティング関連セクションで正式に説明されるようになった。--add-dirフラグや/add-dirコマンドは「ファイルアクセスの許可」に加えて例外的にスキルの読み込みも行うが、settings.jsonのpermissions.additionalDirectoriesは「ファイルアクセスの許可のみ」でスキルは読み込まない、という区別が存在する。複数プロジェクトで共有スキルを使い回したい場合は、settings.jsonに書くのではなく、起動時に--add-dirを渡す運用に変える必要がある。
# settings.jsonのadditionalDirectoriesではスキルは読み込まれない
claude --add-dir "../shared-skills-repo"ケース3: Gitワークツリー内でプロジェクトスキルだけ消える(修正済み)
git worktreeを使って並行開発しているとき、メインのチェックアウトでは動くのにワークツリー側だけプロジェクトスキルが一覧に出てこない、という報告があった。
このIssueはv2.1.87時点の報告でClosed済み。同じ症状が出た場合、まずclaude --versionで現在のバージョンを確認し、明らかに古い場合はアップデートするだけで直ることが多い。
ケース4: descriptionは正しいのに一部のスキルだけ説明が消える(未修正)
配置場所も命名も合っている、YAMLフロントマターも壊れていない、なのに一覧に「スキル名だけ」が表示されて説明文が消えているスキルがある——これは現時点(v2.1.177時点)で未修正のバグとして報告されている。
報告者はファイル側の要因(description文字数、ファイルの行数、更新日時、inode順序、YAMLのクォートスタイル、シンボリックリンクの深さ)を丹念に比較したが、説明が消えるスキルと消えないスキルの間に相関を見つけられなかった。同じ現象がユーザーコマンドやプラグインスキルでも起きているため、SKILL.md側の書き方をどれだけ見直しても直らない可能性が高い。エラーログも一切出ないサイレントな不具合なので、「descriptionを書き直しても直らない」ときはこれを疑ってclaude --versionを確認し、Issueのコメント欄で修正状況を追うのが早い。
ケース5: 説明の途中で切れる・リストから消える
これは未修正バグではなく、仕様上の文字数予算の話。Claude Codeはスキル一覧をコンテキストに常時読み込んでいるが、その一覧に使える文字数には上限がある。予算はモデルのコンテキストウィンドウの1%相当でスケーリングされ、リストがこの予算を超えると、呼び出し頻度の低いスキルから順に説明文が削られていく。
# スキル一覧のコンテキストコストと、削られている原因を確認する
claude doctorclaude doctor(または/doctor)を実行すると、一覧の推定コストと最大の要因になっているスキルが分かる。予算がオーバーしている場合はデバッグログにも警告が出るので、--debug付きで起動して確認するとより詳しい。
対処は3通りある。
- 予算そのものを引き上げる:
settings.jsonのskillListingBudgetFractionを0.02(2%)のように増やす、またはSLASH_COMMAND_TOOL_CHAR_BUDGET環境変数で固定文字数を指定する - 使用頻度の低いスキルを
skillOverridesで"name-only"にして、説明なしで名前だけ一覧に残す descriptionとwhen_to_useのテキスト自体を削る。両者を合算したテキストは予算に関係なく1,536文字でキャップされるため、主要なユースケースを冒頭に書いておく
ケース6: 逆に何を聞いても勝手に発火する
こちらは公式トラブルシューティングでも触れられている定番パターン。descriptionが「〜を手伝います」のように抽象的すぎると、関係ない会話でもClaudeが「これっぽい」と判断して呼び出してしまう。
対処はシンプルで、descriptionをより具体的なトリガーフレーズに絞り込むか、そもそも自動発火させたくないならdisable-model-invocation: trueを付けて手動呼び出し専用にする。ただし次のケースで説明するとおり、このフラグ自体にも落とし穴がある。
ケース7: disable-model-invocation: trueにしたら/skill-nameまで拒否された
disable-model-invocation: trueは本来「Claudeが勝手に自動発火するのを防ぐ」ためのフラグで、ユーザーが/skill-nameで明示的に呼び出す分には問題なく動くはずの仕様になっている。ところが実際には、このフラグを付けた途端にスラッシュコマンドでの呼び出しまでClaudeがSkillツールの実行を拒否する、という報告が複数上がっている。
このIssueは重複としてクローズされているが、明確な修正コミットへの言及は見当たらない。disable-model-invocation: trueを設定したスキルが/skill-nameで呼べなくなった場合、まずはuser-invocable: trueが明示的に書かれているか確認したうえで、それでも呼べないなら現在使っているバージョンで同じ不具合が残っていないか、Issueのコメント欄で最新状況を確認したほうがいい。
ケース8: skillOverridesで"off"にしたのに呼び出せてしまう
チームで共有しているプロジェクトのスキルを、自分の環境だけ.claude/settings.local.jsonのskillOverridesで無効化したいことがある。ところがこの設定で"off"を指定しても、スキルが一覧に残り続け、/skill-nameで普通に呼び出せてしまうという報告がある。
skillOverridesは本来、"on"(名前+説明)・"name-only"(名前のみ)・"user-invocable-only"(非表示だがClaudeは呼べる)・"off"(完全非表示)の4段階で可視性を制御する仕組みだ。設定してもスキルが消えない場合は、.claude/settings.local.jsonと~/.claude/settings.jsonのどちらに書いたかを確認する。プロジェクト側の設定がユーザー側の設定を上書きしていないか、/skillsメニューを開いて実際の状態を目視確認するのが確実な切り分け方法になる。
ケース9: SKILL.mdのYAMLが壊れている(サイレント障害)
frontmatterのYAMLが構文的に壊れている場合、Claude Codeは意外にも「スキル自体を無視する」のではなく「空のメタデータでスキル本体だけ読み込む」という挙動を取る。つまり/skill-nameでの直接呼び出しは動くのに、descriptionが存在しないためClaudeが自動判定に使える情報がなく、結果として「自動発火だけしない」という中途半端な壊れ方をする。
claude --debug--debug付きで起動すると、YAMLのパースエラーがログに出力される。「SKILL.mdを書いたのに自動発火だけしない」ケースでは、まずここを疑ってインデントやコロンの後のスペース、クォートの閉じ忘れがないか確認するといい。
会話が長くなるとスキルの内容を急に無視し始める
これはバグではなく、auto-compactionの仕様。スキルが呼び出されると、その内容は会話の一部として残り続けるが、コンパクション(要約による圧縮)が走ると、各スキルの直近の呼び出し分だけが要約の後に再アタッチされ、最初の5,000トークンが保持される。再アタッチされる全スキル合計で25,000トークンの予算を共有しているため、セッション内で多くのスキルを呼び出していると、古いスキルの中身はコンパクション後に完全にドロップされることがある。
「最初はちゃんと守っていたルールを、途中から急に無視し始めた」と感じたら、コンパクションでスキル本体が落ちている可能性が高い。対処は該当スキルを再度invokeしてフルコンテンツを復元するか、常に効かせたいルールは元々SkillsではなくCLAUDE.mdに書くべき性質のものだったと切り分けるかのどちらかになる。
それでも決定的に動作させたいなら
ここまでの原因を潰しても、Claudeがスキルのdescriptionを見て「今回は使わない」と判断してしまうこと自体は制御できない領域が残る。公式ドキュメントも「スキルのdescriptionと指示を強化してモデルがそれを優先し続けるようにするか、フックを使って動作を決定的に強制する」ことを勧めている。判断の余地を残さず必ず特定の処理を挟みたい場合は、Skillsではなくフックの領域になる。
自分の状況を確認する手順
パニックになってdescriptionを何度も書き直す前に、次の順番で確認するといい。
claude --versionで現在のバージョンを確認するclaude updateまたはnpm update -g @anthropic-ai/claude-codeでアップデートする(ケース3のような修正済みバグを踏んでいないか確認する意味も兼ねる)/skillsメニューを開いて、そのスキルが一覧に出ているか・skillOverridesの状態はどうなっているかを目視するclaude doctorでスキル一覧の文字数予算を確認するclaude --debugでYAMLパースエラーやその他のログを確認する- ここまでで原因が特定できなければ、同じ症状の既存Issueを検索するか新規報告する
skill-creatorで発火の精度を測る
原因の切り分けが終わって「descriptionの書き方自体」を改善したい場合は、公式のskill-creatorプラグインを使うとdescriptionのチューニングを定量的に進められる。
/plugin install skill-creator@claude-plugins-official
/reload-pluginsインストール後、「evaluate my skill-name skill with skill-creator」のようにClaudeへ依頼すると、トリガーすべきプロンプトと、トリガーすべきでないプロンプトの両方を生成してヒット率を測定し、間違ったリクエストでスキルが発火している場合はdescriptionの修正案まで提案してくれる。「なんとなく発火しない気がする」を感覚ではなく数字で確認できるのがこの仕組みの利点だ。
FAQ
disable-model-invocation: trueとuser-invocable: falseはどう違う?
disable-model-invocation: trueはユーザーだけが呼び出せるようにする設定で、副作用のあるデプロイ・送信系のスキル向け。user-invocable: falseは逆にClaudeだけが呼び出せるようにする設定で、/メニューに人間が打つ意味のない背景知識用のスキル向け。両方をtrue/falseの組み合わせで誤って設定すると、どちらからも呼べないスキルが出来上がってしまうので注意したほうがいい。
プロジェクトの.claude/skills/をコミットしても、他のメンバーの環境で動かないことがあるのはなぜ?
ワークスペーストラストダイアログが関係していることが多い。プロジェクトの.claude/skills/にチェックインされたスキルのallowed-toolsは、そのフォルダのワークスペーストラストダイアログを一度承認しないと有効にならない。新しくクローンしたメンバーがまだこのダイアログに同意していない場合、スキル自体は見えていても権限まわりで期待通りに動かないことがある。
descriptionを書き直したのに反映されない
SKILL.md本体のテキスト変更はライブ検出されるが、変更が反映されているように見えない場合、そのスキルが既に一度invokeされていて内容が会話にキャッシュされたまま残っている可能性がある。新しいセッションを開始してから確認するのが確実な検証方法になる。
複数のスキルを同時に呼び出すとどちらか片方しか反応しないことがある
/skill-a /skill-b引数のようにスキルをスタックして呼び出す場合、Claude Codeは最初のスキルと、それに続く最大5つまでのスキルを展開する。展開はインラインで呼び出せないスキル(context: forkで実行されるものなど)に到達した時点で止まるため、6つ目以降やフォーク実行系のスキルの後ろに続けたものは意図通りに展開されない。
まとめ
「Claude Code Skillsが動かない」で一括りにされがちな症状は、実際には「そもそも一覧に出てこない」「自動発火だけしない」「一部だけ説明が消える」「逆に発火しすぎる」「手動呼び出しまで拒否される」という別々の系統に分かれている。このうちワークツリーの検出漏れのようにすでに修正済みのものもあれば、descriptionが非決定的に消えるバグ(#68677)やdisable-model-invocationがスラッシュコマンドまで巻き込む問題のように、2026年8月時点でも未解決のまま残っているものもある。
descriptionを何度も書き直す前に、まずclaude --versionで自分のバージョンを確認し、この記事の早見表と照らし合わせてから対処するほうが結局は早い。それでも当てはまるケースがなければ、同じ環境の報告がないかGitHub Issueを検索してみてほしい。
