スキルが呼ばれないときの直し方｜起きやすい順に 7 つ

まず切り分ける

症状は 2 つに分かれます。どちらかを先に確定させてください。

名前を明示して呼んでみる

確認のしかたは、名前を明示して呼んでみることです。

pdf スキルを使って、この PDF から表を抜いてください。

これで動くなら読み込まれています。問題は description です（原因 4 以降）。これでも動かないなら読み込まれていません（原因 1〜3）。

起きやすい順に 7 つ

1. 原因 1: name が仕様やフォルダ名とずれている実行環境によっては読み込まれない
2. 原因 2: 置き場所が違う読み込まれていない
3. 原因 3: SKILL.md だけを置いている読み込まれていない
4. 原因 4: description が呼び出しの条件になっていない呼ばれるが動かない
5. 原因 5: 似た説明のスキルが競合している呼ばれるが動かない
6. 原因 6: disable-model-invocation: true が付いている呼ばれるが動かない
7. 原因 7: user-invocable: false でメニューに出ない呼ばれるが動かない

読み込まれていない場合

原因 1: name が仕様やフォルダ名とずれている

Agent Skills の仕様では、name の制約はこれだけです（agentskills.io の仕様、2026-10-09 確認）。

• 小文字・数字・ハイフンのみ
• 64 文字以内
• ハイフンで始めない／終わらない。ハイフンを 2 つ続けない
• フォルダ名と完全に一致

やりがちな間違い。

my-skill/
└── SKILL.md   →  name: my_skill   ✕ アンダースコアは使えない
                  name: My Skill   ✕ 大文字と空白
                  name: myskill    ✕ フォルダ名と違う
                  name: my-skill   ○

フォルダ名を変えたときに name を直し忘れるのが典型です。

Claude Code では、ずれても読み込みは止まらない

Claude Code の公式の説明では、name は / のメニューに出るコマンド名で、省略するとフォルダ名になります。フォルダ名でも呼べます（2026-10-09 確認）。

つまり Claude Code では、ずれていても読み込みは止まりません。起きるのは、/ で探している名前と、メニューに出る名前が違うという取り違えです。

仕様に沿っているかは、仕様の検証ツール（skills-ref validate）が確かめます。別の実行環境へ持っていく前に通しておくと安全です。

原因 2: 置き場所が違う

エージェントごとに違います。

両方のエージェントを使っているなら、両方に置く必要があります。片方にしか置いていないのに、もう片方で呼ぼうとしている、という取り違えが起きます。

npx skills add で入れた場合は、-g が付いていたかを確認してください。付いていれば個人環境側、付いていなければプロジェクト側です。

詳しい対比は導入ガイドにあります。

原因 3: SKILL.md だけを置いている

フォルダごと置いてください。参照資料やスクリプトを使うスキルは、それらが無いと動きません。

実データでは azure-prepare が同梱ファイル 165 件、skill-creator が 17 件（うち Python のファイルが 10 件、実行属性つきは 7 件）を持っています（2026-10-09 確認）。SKILL.md は入口で、本体は周りのファイルです。

新しく作ったフォルダは読み直しが要る

Claude Code はスキルのフォルダを見張っていて、足したり直したりしたスキルは再起動なしで読み込みます。ただし、会話を始めたときに無かったスキルの置き場（最上位のフォルダ）を新しく作った場合は /reload-skills が要ります。

Codex も変更を自動で拾い、出てこないときは再起動するよう案内しています（どちらも公式の説明、2026-10-09 確認）。

呼ばれるが動かない場合

原因 4: description が呼び出しの条件になっていない

読み込まれているのに呼ばれない原因は、ほぼこれです。

エージェントはまず説明だけを読み、使うと判断したときに本文を読み込みます。つまり description は紹介文ではなく、呼び出しの条件式です。

悪い例と良い例を並べます。

✕ 対象が広すぎる

description: コードの品質を改善します。

「コードを触る作業」全部が該当しうるので、いつ呼ぶべきか決まりません。呼ばれるときもあり、呼ばれないときもある、という不安定な状態になります。

○ 条件を列挙する

description: React コンポーネントの再レンダリングを減らす。
  useMemo / useCallback / memo の使いどころと、使うべきでない場面を扱う。
  「描画が遅い」「再レンダリングが多い」「プロファイラで確認したい」
  といった依頼で使う。CSS の見た目やアクセシビリティには使わない。

違いは 4 点です。

• 対象を絞っているReact の再レンダリングに限定
• 利用者が実際に打つ語を入れている「描画が遅い」
• 固有名詞を並べているuseMemo useCallback
• 使わない場面を書いているCSS、アクセシビリティ

frontmatter が壊れていても、同じ症状になる

Claude Code の公式の手引きによると、frontmatter の YAML が壊れていると、本文は読み込まれますが説明は空になります。/名前 では動くのに、自動では当たらない状態です。--debug を付けて起動すると、読み取りの失敗が出ます（2026-10-09 確認）。

実測: 実際に流通しているスキルはどれくらい書いているか

当サイトが収録している 470 件の SKILL.md を測りました。2026年9月19日時点です。

frontmatter が無い 1 件を除いた 469 件の集計で、YAML のブロック記法（> |）は展開してから数えています。

最短

18 文字

中央値

373 文字

平均

412 文字

最長（仕様上の上限は 1,024 文字）

1,068 文字

中央値 373 文字。「1 行で簡潔に」と書いた解説をよく見ますが、実際に流通しているものはそうなっていません。

Anthropic 公式はさらに長い

Anthropic 公式はさらに長く書いています。

測り方と項目の詳細はSKILL.md の書き方にあります。

原因 5: 似た説明のスキルが競合している

説明が近いスキルが複数あると、どれが呼ばれるか安定しません。

たとえば「テストを書く」に関わるスキルが 3 つ入っていると、依頼のしかたによって別のものが呼ばれます。本人からは「呼ばれない」ように見えます。

直し方は 2 つ。

• 1 つの用途につき 1 つに絞る使っていないものは外す
• 「使わない場面」を書くそれぞれの description に書く。境界がはっきりすれば競合が減ります

切り分けには、疑わしいスキルを一時的に外して試すのが確実です。

原因 6: disable-model-invocation: true が付いている

これが指定されていると、自動では呼ばれません。/名前 で手動で呼ぶ形になります。仕様どおりの挙動です。

実データでは 470 件中 23 件がこれを使っています（2026-09-19 時点）。影響の大きい作業（アーキテクチャの改修など）に付いていることが多く、意図せず発動しないための指定です。

SKILL.md の先頭を見て、この行があれば手で呼んでください。

原因 7: user-invocable: false でメニューに出ない

原因 6 の逆です。手動のメニュー（/）には出ませんが、エージェントの判断では呼ばれます。

実データでは 7 件が使っています（2026-09-19 時点）。「/ で探しても出てこない」ときは、この指定を疑ってください。呼びたい場合は、依頼文でスキル名を明示します。

直したあとに確かめる

書き直したら、本当に効いたかを確認してください。「たぶん直った」で終わらせると、次に同じ調査をやり直します。

確かめ方が 2 つある

• writing-skillsスキル無しでどう外すかを先に観測し、差分だけを書く
• skill-creatorお題を作って走らせ、結果を定量の指標で見る

skill-creator には説明文だけを最適化する専用のスクリプトがあります。呼ばれない症状に限れば、ここだけ使うのが最短です。

writing-skills の指摘

writing-skills の指摘が本質的なので引きます。

スキル無しでエージェントが失敗するのを見ていないなら、そのスキルが正しいことを教えているかは分からない。

切り分けの早見表

よくある質問

description を長くすると、呼ばれすぎませんか

その心配は「使わない場面」で抑えられます。条件を足すのは「いつ呼ぶか」を広げる作業ではなく、輪郭をはっきりさせる作業です。

実データで Anthropic 公式の xlsx は 948 文字ありますが、その中に「成果物が Word 文書や HTML レポートの場合は使わない」という除外条件が入っています。長い説明は、境界も書けます。

日本語で書いても呼ばれますか

呼ばれます。ただし判定に効くのは、利用者が実際に打つ言葉です。日本語で依頼するなら日本語の語を入れてください。英語と日本語を併記しても構いません。

実データでは 470 件のほぼ全部が英語ですが、それは公開元が英語圏だからで、日本語が不利なわけではありません。

公開されているスキルが呼ばれないときは

description を自分で書き換えて構いません。取り込んだスキルはローカルのファイルです。

ただし書き換えると原本との差分ができるので、更新を追うかどうかを決めておいてください（社内でスキルを配布する方法）。

複数のエージェントで挙動が違います

置き場所と読み込みの仕組みが別なので、揃うとは限りません。

SKILL.md の標準は共通ですが、disable-model-invocation や user-invocable は Claude Code の拡張項目で、他の実行環境が同じように解釈する保証はありません。

当サイトは各スキルのページで、公開元が対応を明記しているエージェントだけを表示しています。明記が無いものは、実際に動くとしても当サイトでは断定しません。