Claude CodeでSkillが一覧には出ているのに、期待した依頼で自動的に使われない場合、Skill本体よりも「Claudeに見えているメタデータ」と「依頼文との一致」を先に確認すると切り分けやすくなります。Claude Codeでは、通常はSkillの名前とdescriptionがコンテキストに入り、Claudeが関連すると判断したときに本文を読み込みます。つまり自動呼出しは単純な文字列一致のトリガーではありません。この記事では、Skillが認識済みであることを前提に、設定・description・依頼文・手動実行の順で原因を切り分けます。
まず結論：Skillが呼ばれないときは「禁止設定→description→依頼文→手動実行」の順で確認する
Claude CodeのSkillは、通常セッションでは名前とdescriptionがClaudeに提示され、タスクとの関連性をClaudeが判断して必要なときに本文を読み込みます。そのため「この語が含まれたら必ず発火する」という固定ルールではありません。まず自動呼出しが禁止されていないかを確認し、その次にdescriptionと依頼文の対応を見ます。
| 確認順 | 確認するもの | 分かること |
|---|---|---|
| 1 | disable-model-invocation / skillOverrides | そもそもClaudeから自動呼出し可能なSkillか |
| 2 | description / when_to_use | Claudeが「いつ使うSkillか」を判断できる説明になっているか |
| 3 | frontmatter YAML | descriptionが正しくメタデータとして読み込まれているか |
| 4 | 実際の依頼文 | descriptionに書いた用途とユーザーの言い方が対応しているか |
| 5 | /skill-nameで直接実行 | Skill本体の問題か、自動選択だけの問題か |
| 6 | Hooksなど別手段 | 毎回必ず実行したい処理をモデル判断に任せる設計になっていないか |
Skillが`/skill-name`では正常に動くなら、SKILL.md本文やツール処理よりも、自動呼出しの可視性・description・マッチング側を疑うのが近道です。
最初に「Claudeから自動呼出しできる設定か」を確認する
最初に見るべきなのはfrontmatterの`disable-model-invocation`です。これが`true`なら、そのSkillはユーザーが`/skill-name`で明示実行するためのSkillとなり、Claudeは自動で呼び出しません。デプロイや送信など、実行タイミングを人間が握りたい処理向けの設定です。
---
name: review-api
description: API変更をレビューし、破壊的変更や入力検証漏れを確認する
# true だとClaudeからの自動呼出しを禁止する
disable-model-invocation: false
---さらに現在のClaude Codeでは`skillOverrides`でSkillの見え方を上書きできます。`user-invocable-only`ではClaude側から隠れ、`off`ではメニューも含めて無効になります。`name-only`はClaudeに名前だけを見せ、descriptionを省く設定なので、自動選択を期待するSkillでは意図した設定か確認してください。
用語解説：disable-model-invocation
`true`にするとClaude自身によるSkillの自動呼出しを禁止するfrontmatter設定です。手動実行専用のワークフローにしたい場合に使います。
descriptionには「何をするか」だけでなく「いつ使うか」を書く
Skillが自動で呼ばれるかを左右する中心情報が`description`です。公式ドキュメントでは、ClaudeがSkillを適用する判断にdescriptionを使い、必要なら`when_to_use`でトリガーとなる状況や例を補足できると説明されています。
| 弱いdescription | 改善例 |
|---|---|
| コードを確認するSkill | API・バックエンドの変更をレビューするときに使う。入力検証、互換性、エラー処理、テスト漏れを確認する |
| ドキュメント作成を支援する | README、設計書、手順書の草案または更新を依頼されたときに使う。既存文書の構成と用語を維持する |
| テストを手伝う | 実装変更に対してテスト追加・不足ケース・境界値の確認を依頼されたときに使う |
ポイントは、抽象的な能力説明ではなく、ユーザーが実際に依頼するときの言葉を含めることです。主要な用途はdescriptionの前半へ置き、複数の具体例が必要なら`when_to_use`へ分けます。
---
name: api-review
description: API・バックエンドの変更をレビューするときに使う。入力検証、互換性、エラー処理、テスト漏れを確認する。
when_to_use: |
「APIをレビューして」「このエンドポイントの変更を確認して」
「破壊的変更がないか見て」のような依頼で使う。
---
YAMLが壊れていると「手動では動くのに自動では呼ばれない」ことがある
SKILL.mdのfrontmatterが不正なYAMLになっている場合も注意が必要です。現在の公式トラブルシュートでは、YAMLの解析に失敗するとSkill本文は読み込めてもメタデータが空になり、`/skill-name`では動く一方、Claudeが自動選択に使うdescriptionを持てないケースが説明されています。
---
name: api-review
description: "API変更をレビューするときに使う"
---
# API Review
変更差分を確認し、入力検証・互換性・テストをレビューする。「直接呼べるからfrontmatterも正常」とは限りません。自動呼出しだけ失敗する場合は、引用符、インデント、`—`の位置なども確認し、必要ならClaude Codeを`–debug`で起動して解析エラーを見ます。
依頼文をdescriptionに近づけて、自動選択だけの問題かテストする
設定とYAMLに問題がなければ、実際の依頼文とdescriptionの意味が十分に近いかを確認します。公式ドキュメントのトラブルシュートでも、Skillが発火しない場合はdescriptionにユーザーが自然に使うキーワードを含め、依頼文をdescriptionへ近づけて試す方法が案内されています。
| テスト | 例 | 目的 |
|---|---|---|
| should-trigger | 「このAPI変更をレビューして。入力検証と互換性も確認して」 | descriptionに書いた代表用途で呼ばれるか |
| 言い換え | 「このエンドポイント変更に破壊的変更がないか見て」 | 自然な別表現でも用途を判断できるか |
| should-not-trigger | 「APIのRESTとは何か説明して」 | 関連語だけで不要にSkillが呼ばれないか |
自動呼出しを強くしたいからといって、descriptionへ無関係なキーワードを大量に足すと逆に誤発火しやすくなります。「何をする」「どの依頼で使う」「どの依頼では使わない」を少数の代表ケースで評価する方が調整しやすくなります。
（AIコーディングへの依頼を対象・条件・期待結果まで具体化する考え方も確認したい場合については『AI に“思い通り”のコードを書かせるには？JavaScript／CSS で失敗しないプロンプト改善術【ChatGPT活用】』をご参照ください）
Skillが多い環境ではdescriptionの表示予算も確認する
多数のSkillを入れている環境では、Skill一覧をClaudeへ渡すためのコンテキスト予算も確認対象になります。公式ドキュメントでは、各Skillの`description`と`when_to_use`は一覧上で上限までに切り詰められ、全Skillを掲載するための予算も設定されていると説明されています。
そのため、重要な用途をdescriptionの末尾に長く書くより、最初に置く方が安全です。低優先度Skillを`name-only`へ変更して一覧の説明量を減らす方法もあります。ただし、これはSkill数が多い場合の追加確認であり、少数Skillしかない環境では最初からここを疑う必要はありません。
まず/skill-nameで直接実行し、Skill本体と自動呼出しを分離する
原因を短時間で切り分けるには、対象Skillを`/skill-name`で直接実行します。直接実行で想定どおりの手順が動くなら、Skill本文・参照ファイル・スクリプトは概ね利用できており、問題は自動呼出し側に絞れます。
/api-review
この変更をレビューしてください。| 結果 | 次に見る場所 |
|---|---|
| 手動実行は成功、自動だけ失敗 | disable-model-invocation、skillOverrides、description、when_to_use、依頼文 |
| 手動実行も失敗 | SKILL.md本文、参照パス、スクリプト、allowed-tools、実行エラー |
| Skill自体が候補に見えない | 配置場所・Skill認識・新規top-level skillsディレクトリなどを別途確認 |
本記事は「Skillは認識されているのに呼ばれない」ケースが対象です。Skill自体が一覧に出ない場合は、配置・ディレクトリ監視・SKILL.md認識の問題として分けて調べた方が混乱しません。
毎回必ず実行したい処理はSkillの自動選択だけに任せない
Skillの自動呼出しはClaudeの関連性判断を使います。したがって「ファイル編集のたびに必ずLintを走らせる」「特定コマンドを必ずブロックする」のような決定的な動作を、Skillのdescription調整だけで保証しようとするのは向いていません。
| やりたいこと | 向いている仕組み |
|---|---|
| 状況に応じて再利用手順を使ってほしい | Skillの自動呼出し |
| 人間が実行タイミングを決めたい | /skill-name + disable-model-invocation |
| 特定イベントで必ず処理したい | Hooks |
| 常時参照するプロジェクト規約を伝えたい | CLAUDE.mdやRules |
Anthropicの公式解説でも、Skillsは手順を必要なときに読み込む仕組み、Hooksはライフサイクルイベントで決定的に動かす仕組みとして分けられています。発火率を100%へ近づけるためにSkillを複雑化するより、要件そのものが「必ず実行」なら仕組みを変える方が明確です。
よくある質問
descriptionに特定のキーワードを書けば、必ずSkillが呼ばれますか？
必ずではありません。Claude CodeはSkillのname・descriptionなどを見て関連性を判断します。キーワードは判断材料になりますが、固定の文字列トリガーとして保証される仕組みではありません。必ず実行したい処理はHooksや明示的な/skill-name実行を検討してください。
Skillが/メニューに出ていれば、自動呼出しも有効ですか？
必ずしも同じではありません。`disable-model-invocation: true`ならユーザーは手動実行できてもClaudeは自動呼出しできません。またskillOverridesの状態によってClaude側への表示とメニュー表示が分かれるため、両方を確認してください。
user-invocable: falseにするとClaudeもSkillを使えなくなりますか？
いいえ。現在の公式仕様では`user-invocable: false`は主にユーザーの/メニューから隠す設定で、Claudeによる呼出しは可能です。Claudeからの自動呼出しを止める場合は`disable-model-invocation: true`を使います。
descriptionを直したのに同じセッションで変化しません。再起動が必要ですか？
通常、監視対象の既存Skillディレクトリ内の追加・編集・削除はセッション中にも反映されます。ただしSkillが一度読み込まれた後の内容や、作成したディレクトリ構成によって切り分けが必要です。まずSkill一覧と現在のdescriptionが期待どおり見えているかを確認してください。
まとめ：自動呼出しは「Skillがあるか」ではなく「Claudeにどう見えているか」を確認する
- `disable-model-invocation: true`ならClaudeからの自動呼出しは行われない
- `skillOverrides`でClaude側からdescriptionが隠れていないか確認する
- `description`には何をするSkillかだけでなく、どんな依頼で使うかを書く
- YAMLが壊れると手動実行はできてもdescriptionが自動選択に使われない場合がある
- 実際の依頼文をdescriptionへ近づけてshould-trigger / should-not-triggerを試す
- `/skill-name`で手動実行し、Skill本体と自動呼出しを切り分ける
- 毎回必ず実行する処理はHooksや手動実行の方が適している
最初に試すなら、対象Skillを手動で一度実行して正常性を確認し、その後`disable-model-invocation`とskillOverridesを確認してください。そこに問題がなければ、descriptionの先頭を「どの依頼で使うか」が分かる文章へ直し、実際のユーザー依頼で再テストすると原因を絞り込みやすくなります。
