Claudeのスキルが発動しない原因|自動で呼ばれない時の直し方

Claude CodeやClaudeのWeb版で自作したスキルが、「/名前」で呼べば動くのに、普通に頼んだときには使われないことがあります。スキルが壊れているわけではなく、Claudeが「今はこのスキルを使う場面だ」と判断できていない状態です。

本記事では、公式ドキュメントと公式ヘルプ、GitHubに寄せられた報告をもとに、原因を「説明文の中身」「説明文が届いていない」「自動で使わない設定」「Claudeが使わずに進む」の4つに分けて、見分け方と直し方を解説します。

Claudeのスキルが発動しないとは

登録はできているのに頼んでも使われない状態

スキルは「/名前」で呼ぶほかに、Claudeが会話の内容から判断して自分で読み込むこともできます。この動きが起きず、合う作業を頼んでもClaudeが自力で進めてしまうのが、本記事で扱う「発動しない」状態です。

画面にエラーは出ないため、登録されていないのか、登録済みで使われていないだけなのかを最初に分けます。

「/名前」で呼べるかで見分ける

入力欄に「/」とスキルの名前を打って呼んでみてください。これで動くなら登録はできているので、本記事の4つの原因のどれかに当たります。「Unknown skill」と出るなど「/名前」でも動かない場合は、登録の段階の問題なので次の記事を先に確かめてください。

関連記事:Claude Code「Unknown skill」の原因|スキルが呼べない時の直し方

原因1:説明文が頼み方と合っていない

Claudeは説明文を見て使うかを決める

スキルを使うかどうかの判断材料は、SKILL.mdの冒頭に書く説明文(description)です。Claude Codeの公式ドキュメントは、説明文を「何をするか、いつ使うか」を書く欄とし、Claudeはこれを見て使う場面を決めるとしています。

同じドキュメントのトラブル節で、発動しないときに最初に確かめる項目として挙げられているのが次の1文です。

Check the description includes keywords users would naturally say(訳)利用者が自然に口にする言葉が、説明文に入っているか確かめてください

「何をするか」と「いつ使うか」の両方を書く

公式ドキュメントの見本では、説明文が「何をするか」の文と「Use when〜(こういうときに使う)」の文の2つでできています。

description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.

前半で「まだコミットしていない変更をまとめ、危ない箇所を指摘する」と働きを書き、後半で「何が変わったか聞かれたとき」など頼まれ方を並べています。日本語で頼むことが多いなら、後半に日本語の言い回しも入れておきます。

説明文は三人称で具体的な言葉を入れる

開発者向けのスキル作成ガイドは、説明文を必ず三人称で書くよう求めています。説明文はシステムプロンプト(Claudeへの前提の指示)に入るため、「私が〜します」「あなたは〜できます」と視点がぶれると見つけにくくなるとされています。

あわせて、扱うファイルの種類など具体的な言葉を入れるよう案内されており、避ける例は「Helps with documents(書類を手伝う)」「Processes data(データを処理する)」のような、何にでも当てはまる書き方です。

原因2:説明文がClaudeに届いていない

頭の「---」が1行目にないと説明文が読まれない

Claude Codeは、SKILL.mdの1行目が「---」のときだけ、そこから次の「---」までを頭の項目(name・descriptionなど)として読みます。1行目に空行やタイトルがあると、全体が本文として扱われます。

頭の項目の書き方が壊れている場合も、本文は読み込まれますが項目は空のままです。この状態では「/名前」は動くのに、Claudeは説明文と照合できません。

項目名を1文字でも間違えると、エラーを出さずにその項目が無視されます。読み込みのエラーは claude --debug で起動すると確認できます。

スキルが多いと説明文が削られる

Claude Codeがスキルの名前と説明文をClaudeに渡す一覧には、文字数の枠があります。

The listing always contains every skill name, but if you have many skills, Claude Code drops some descriptions to fit the listing's character budget, which removes the keywords Claude needs to match your request.(訳)一覧には必ずすべてのスキル名が載りますが、スキルが多いと枠に収めるため一部の説明文が落とされ、照合に要る言葉が消えます。

枠の大きさは、使うモデルが一度に扱える文脈の長さの1%です。あふれたときは呼ばれる回数の少ないスキルから説明文が落とされるため、作ったばかりのスキルほど名前だけになりやすくなります。

一覧の大きさは /doctor で目安が分かり、使っていないスキルは /skill-doctor(v2.1.252以降)で見つけられます。枠を広げるには、設定の skillListingBudgetFraction(例:0.02で2%)か環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET を使います。説明文1件も、補足欄のwhen_to_useと合わせて1,536文字で切られるので、大事な使い道は先頭に書きます。

Claude(Web版)では説明文は200文字まで

Web版やデスクトップアプリでアップロードするスキルは、スキルの作り方の公式ヘルプに「Claude はこれを使用してスキルを呼び出すかどうかを判断します(最大 200 文字)」とあります。Claude Codeの1,536文字とは別の決まりなので、手順の説明は本文に回し、説明文には頼まれ方の言葉を優先して入れます。

原因3:自動で使わない設定になっている

disable-model-invocationを付けている

頭の項目に disable-model-invocation: true があると、Claudeはそのスキルを自分では呼びません。説明文もClaudeに渡らなくなるため、どれだけ頼み方を合わせても自動では使われません。

デプロイやメッセージ送信のように、使う時機を人が決めたい作業のための設定です。人のスキルを写して作ったときに残っていることがあるので、自動で使ってほしいなら外します。

/skillsで名前だけ・手動だけにしている

設定の skillOverrides でも、スキルの見え方を変えられます。/skills の画面でスキルを選んでSpaceキーを押すと状態が切り替わり、Escで .claude/settings.local.json に保存されるので、知らないうちに切り替えていないか確かめてください。

設定の値 Claudeに渡るもの 「/」のメニュー
on(初期値) 名前と説明文 出る
name-only 名前だけ 出る
user-invocable-only(画面ではuser-only) 渡らない 出る
off 渡らない 出ない

name-onlyでは照合に使える言葉が名前だけになり、user-invocable-onlyは「/名前」で呼ぶ専用です。また、/permissions の拒否の欄に「Skill」と書くとすべてのスキルが、「Skill(deploy *)」のように書くと個別のスキルが止まります。

Claude(Web版)はスキルのスイッチとコード実行がオンか

Web版とデスクトップアプリでは、コード実行がオンであることがスキルの前提です。スキルの使い方の公式ヘルプには、「Code execution and file creationがオンの場合、Claude は関連するときにこれらのツールを自動的に使用します」とあります。

  • 個人のプラン:Settings > Capabilitiesの「Code execution and file creation」(新しい設定画面では「Create and edit files」)がオンか
  • TeamとEnterprise:管理者がOrganization settings > Plugins & skillsの「Policy」タブで、コード実行とSkillsを有効にしているか
  • スキルごとのスイッチ:Customize > Skillsで、そのスキルのスイッチがオンか

同僚から共有されたスキルは、自分でオンにするまでオフのままです。

原因4:合っていてもClaudeが使わずに進む

合う頼み方でも使わない報告が続いている

説明文と設定に問題がなくても、Claudeがスキルを使わずに進むという報告があります。GitHubの報告(#9716)では、説明文に合う質問をしたのにClaudeが自分でファイルを探し始めたとされ、2025年10月の起票からコメント69件・反応75件が付いて11月14日時点で未解決です。

2026年3月の報告(#30387)では、CLAUDE.mdの手順をスキルへ移したら呼ばずに進むことが増えたとされ、4月に「対応予定なし」で閉じられました。

どのくらいの割合で自動で使われるかの公式の数字はありません。確実に使わせたい作業は、手順4の方法で呼ぶのが安全です。

paths付きのスキルは対象のファイルを読むまで出てこない

頭の項目に paths を書いたスキルは、対象のファイルをClaudeが読んだり編集したりして初めて使えるようになります。公式ドキュメントでは、そのファイルがClaude Codeを起動した作業フォルダの外にあると出てこないとされ、/add-dirで足したworktreeも対象外です。

さらに、オートモードではファイルの読み書きをBash経由で行うため、paths付きのスキルが出てこないという報告(#90004)もあります(2026年8月起票・11月14日時点で未解決)。

確認と直し方の順番

手順1:一覧に出ているかClaudeに聞く

公式ドキュメントの手順に沿って、Claudeに使えるスキルを聞きます。

What skills are available?

目的のスキルが出てこなければ登録の段階の問題、出てくるのに使われないなら原因1〜3を見直します。

関連記事:Claude Code「No skills found」の原因|スキルが出ない時の直し方

手順2:説明文を書き直して頼み方で試す

説明文を「何をするか」と「いつ使うか」の2文に直し、普段の言い回しを後半に入れてから、使われるはずの頼み方を何通りか試します。

Web版では、作り方のヘルプにあるとおり、Claudeの思考を見てスキルが読み込まれたかを確かめ、使われなければ説明文を直します。

手順3:claude plugin validateで頭の書き方を検査する

説明文を直しても変わらないときは、頭の項目が壊れていないかを検査します(v2.1.233以降)。

claude plugin validate .claude/skills

個人のスキルは ~/.claude/skills を指定します。古い版なら先に claude update で更新してください(11月14日時点の最新はv2.1.325)。

手順4:確実に使いたい作業は「/名前」で呼ぶ

毎回使わせたい作業は、Claudeの判断に任せず「/名前」で呼ぶのが確実です。スキルの中に必ず守らせたい決まりがある場合は、フック(決まった操作のたびに自動で動く仕組み)へ移すよう公式ドキュメントは案内しています。

図解:確認と直し方の順番

まとめ

Claudeのスキルが自動で使われるかは、Claudeが説明文と頼み方を見比べて決めます。「/名前」で呼べるのに発動しないなら、説明文の書き方、説明文が届いているか、自動で使わない設定のどれかをまず疑います。

まずClaudeに「What skills are available?」と聞いて一覧に出るかを確かめ、出ていれば説明文の書き直しから始めてください。毎回必ず使わせたい作業は「/名前」で呼びます。

メルマガ登録CTA B2(MCPカオスマップ無料プレゼント)