Claude の Skill が自動で動かない理由と直し方

結論から

Skill を名前で呼び出して動くなら、インストールはできています。自動で動くかどうかは description しだいで、エージェントはそれを最初に読み、短縮することもあります。この 2 つは失敗の原因が異なるので、別々に試しましょう。

各エージェントが Skill を選ぶ仕組み

どのエージェントも、まず Skill の名前と description の一覧を読み、Skill を選んでから初めてその指示全体を読み込みます。この一覧は各 SKILL.md（skills.md で検索する人も多いファイル）の frontmatter から作られ、使える容量には上限があります：

エージェント	最初に読むもの	容量が足りなくなると
Claude Code	名前と description、設定されていれば `when_to_use` も。それぞれ最大 1,536 文字	一覧に割り当てられるのはコンテキストウィンドウの約 1%。使用頻度の低い description から外れていきます
Codex	名前、description、ファイルパス	一覧に割り当てられるのはコンテキストウィンドウの約 2%。まず description が短縮されます
Cursor	名前と description	記載なし

Skill を多数インストールしていると、長い description やあいまいな description は、エージェントが検討する前に切り詰められたり外されたりします。だからこそ、最初の 1 文が最も重要なのです。

チームメイトが仕事を頼むときの言葉で description を書き、主な用途を最初の 1 文に入れましょう。

エージェントはあなたの依頼をこれらの言葉と照らし合わせます。「landing page」「launch page」「pitch deck」など、実際に入力される言葉を使いましょう。まず成果物を書き、次にいつ使うのかを書きます。

選ばれる

何を作り、いつ使うのか

“Build a product launch page with a hero, feature grid, and pricing toggle. Use when asked for a landing or launch page.”

埋もれる

汎用的

次の順番でテストします。最初のステップでインストールの問題を除外できるので、それ以降に失敗した場合の原因は description です。

たいていは 2 つの description が重なっているか、同じ Skill が 2 回インストールされています。

使いたい Skill を名前で呼び出す。名前での呼び出しは必ず優先されます。
重なっている description を入力・対象・成果物で絞り込み、各 Skill の役割を明確にする。
同じ名前が 2 か所にある場合：Claude Code は Enterprise、個人、プロジェクトの順に優先します。Codex は両方を表示することがあります。コピーは 1 つだけ残してください。

まず名前で呼び出してください。それで失敗するなら、エージェントが探す場所に Skill がインストールされていません。普通の依頼だけが失敗するなら、実際に入力する言葉を使って description を書き直してください。

すべての Skill の名前と description を読み、依頼に最も合うものを読み込みます。/skill-name と入力すれば、この照合をスキップして指定した Skill を実行します。

Skill が何を作り、いつ使うのかを書き、主な用途を最初の 1 文に入れます。description は短縮されることがあるため、「landing page」や「pitch deck」など、実際に入力される言葉を使いましょう。

SKILL.md で、各 Skill フォルダに 1 つずつあります。その frontmatter に、エージェントが Skill を選ぶときに読む名前と description が入っています。

このガイドは役に立ちましたか？