スキルを書いたのに呼び出されない、というのはよくある詰まり方です。原因はたいてい決まったところにあり、切り分ける順番さえ守れば短時間で片が付きます。この記事では「起動しない」「読み込まれない」「別のスキルが使われる」「実行時に落ちる」の4つに分けて、公式チュートリアルとドキュメントの記載にもとづいて直し方を整理します。
まず検証コマンドで構造を確かめる
デバッグに時間を使う前に、まず検証ツール（agent skills verifier）を通してください。公式チュートリアルが最初に挙げているのがこれです。構造上の問題ならここで見つかるので、説明文を書き直したり設定を疑ったりする作業を丸ごと省けます。
インストール方法は OS によって異なりますが、uv を使うのがいちばん速いと案内されています。スキルのディレクトリに移動してから実行しても、別の場所から実行してもかまいません。
Claude Code 側にも点検用のコマンドがあります。/skill-doctor は、使われていないスキル、スキルが消費しているコンテキストのコスト、最近使っていないプラグインを一覧にします。個々のスキルが壊れているかどうかではなく、手元のスキル全体が今どうなっているかを見る道具です。Claude Code v2.1.252 以降で使えます。
この2つを先に通しておくと、以降の切り分けが「構造は正しい前提で、なぜ選ばれないのか」に集中できます。
スキルが起動しないとき
ファイルは正しく置いたのに呼び出されない。このとき原因はほぼ必ず説明文（description）です。
Claude はスキルを意味で照合します。つまり、あなたのリクエストの意味と、説明文の意味が重なっている必要があります。どちらも自然な日本語・英語で書かれていても、語彙が噛み合っていなければ選ばれません。
直し方は、説明文を「自分が実際にどう頼んでいるか」と突き合わせることです。頭の中で考えた正式名称ではなく、実際にタイプしている言い回しを説明文に入れます。公式チュートリアルは、たとえば「help me profile this」のような、ユーザーが現に使う表現をトリガーとして説明文に足すことを勧めています。言い換えのバリエーションも用意して、何通りかの頼み方で実際に試してください。
説明文そのものが読まれていない場合もあります。frontmatter の YAML はファイルの1行目から始まる --- でなければ認識されません。ドキュメントの記載は次のとおりです。
Claude Code reads the frontmatter only when the opening
---is the file's first line. Otherwise it treats the whole file,---markers included, as skill content.
つまり --- の前に空行やコメントが1行でもあると、frontmatter ごと本文として扱われ、説明文は存在しないことになります。
もうひとつ、YAML のパースに失敗しても読み込み自体は成功してしまうという挙動があります。この場合フィールドが何も設定されていない状態でスキルが載るため、「エラーは出ていないのに選ばれない」という分かりにくい形になります。説明文を直しても変わらないときは、YAML の文法を疑ってください。
スキルが読み込まれないとき
そもそも一覧に出てこない場合は、構造の要件を1つずつ確認します。
SKILL.mdは名前付きディレクトリの中に置きます。 スキルの置き場所の直下にSKILL.mdを裸で置いても読み込まれません。skill-name/SKILL.mdという形にします。- ファイル名は正確に
SKILL.mdです。 「SKILL」は全て大文字、拡張子の「md」は小文字。Skill.mdやskill.MDは別物として扱われます。 - ディレクトリ名がそのままコマンド名になります。
.claude/skills/deploy/SKILL.mdなら/deployです。
ディレクトリの中に補助ファイルを置く構成は次のようになります。
skill-name/
├── SKILL.md (必須)
├── reference.md
├── examples.md
└── scripts/
└── helper.pyここまで見ても分からないときは claude --debug で起動します。出力のなかから自分のスキル名に言及している行を探すのが読み方です。読み込みの段階で弾かれているのか、読み込まれた上で選ばれていないのかが、ここで切り分けられます。
プラグイン由来のスキルが出てこない場合は、キャッシュが原因のことがあります。キャッシュを消し、Claude Code を再起動し、それでも駄目ならプラグインを入れ直します。
別のスキルが使われる・優先順位が競合する
意図と違うスキルが動くときは、説明文どうしが似すぎていないかを見てください。意味で照合している以上、近い説明文が2つあれば、どちらが選ばれるかは安定しません。説明文を書き分けて、担当範囲をはっきりさせるのが対処です。
名前が同じスキルが複数ある場合は、優先順位の規則で決まります。ドキュメントの対応表は次のとおりです。
| 同じ名前がある場所 | どれが動くか |
|---|---|
| enterprise・personal・project のうち2つ | enterprise > personal > project |
| 任意の場所と同梱スキル | 自分のスキルが同梱コマンドを置き換える |
スキルと .claude/commands/ のファイル | スキル |
| プロジェクトルートのスキルと入れ子のスキル | 両方読み込まれる（修飾名で呼び分け可能） |
| プラグインのスキルとローカルのスキル | 両方読み込まれる（プラグイン側は名前空間付き） |
とくに引っかかりやすいのが1行目です。組織の管理設定（enterprise）で配られたスキルは、同名の個人スキルを上書きします。 自分の手元にあるファイルを何度直しても挙動が変わらない、という状況はこれで起きます。対処はスキル名を変えるか、管理者に相談するかのどちらかです。
入れ子のスキルは名前が重なっても両方残り、apps/web:deploy のようなディレクトリ修飾名で呼び分けられます。呼び分けの詳しい話はスキルの共有の記事で扱っています。
実行時に落ちるとき
スキルは選ばれて動き出したのに、途中で失敗する場合は次の3点を順に見ます。
- 依存関係の不足。 スキルが外部のコマンドやライブラリを前提にしているなら、それを説明文に書いておきます。書いておけば、環境に無いときに何が足りないのかが分かる形で止まります。
- 実行権限。 スクリプトを同梱している場合、
chmod +xが当たっていないと実行できません。 - パス区切り文字。 Windows を含め、すべてスラッシュ（
/）で書きます。 バックスラッシュを使うと環境によって解釈が変わります。
ツールの許可設定で止まっている可能性もあります。スキル側では frontmatter の allowed-tools（例: allowed-tools: Read Grep）で使えるツールを絞れますし、設定側では Skill(commit) や Skill(review-pr *) のような形で個々のスキルを許可・拒否できます。Skill(deploy *) を拒否に入れていればそのスキルは動きません。落ちる位置がツール呼び出しの手前なら、ここを確認してください。
全体を通しての進め方をまとめます。検証ツールで構造を確かめる、起動しないなら説明文を疑う、読み込まれないならファイル名とディレクトリを確かめる、別のスキルが動くなら優先順位を確かめる、実行時に落ちるなら依存・権限・パスを見る。 この順に当たれば、たいていの不具合はどこかで引っかかります。手当たり次第に設定をいじる前に、まず検証ツールを通す——これがいちばん時間の節約になります。
本記事は Claude Academy の公式チュートリアル「Troubleshooting skills」および Claude Code 公式ドキュメント「Extend Claude with skills」の記載内容にもとづく非公式の日本語解説です（確認日 2026-09-24）。仕様は更新されることがあるため、最新の内容は公式サイトをご確認ください。