書いたスキルが、思った場面で呼ばれない。
description に「いつ使うか」を丁寧に書いたのに、その場面が来ても Claude は普段どおり処理して終わる。私はこれを、自分の書き方が下手なせいだと思っていました。何度も書き直しました。
違いました。書いた description が、Claude に届く前に削られていました。
本記事は Zenn 版の転載・大幅加筆です。Zenn 公開後に「発火しない」の構造的な原因が公式ドキュメントに書かれていると知り、自分の環境で実測し直したので、その結果を中心に書き直しました。
この記事は、Claude Code のスキルを自分で書き始めた人が詰まる 3 つの壁と、その越え方をまとめたものです。私は数か月運用して、順番にこの 3 つに当たりました。
壁1: 書いたのに呼ばれない。
description を丁寧に書いても発火しない。私は自分の書き方が下手なせいだと思っていました。実際は違って、スキルの本数が増えると、書いた説明文が自動で削られる仕組みがあります。書き方以前の問題でした。
壁2: 効いているのか分からない。
「あった方が良さそう」でスキルを増やしていくと、そのスキルが実際に出力を変えているのか、誰も確認していない状態になります。効いていないスキルは、置いてあるだけで害になります。確かめる方法があります。
壁3: 増えすぎて、何が邪魔をしているか見えない。
私の環境で調べたら、自分で書いてもいない「もらってきたスキル」が、壁1 の原因を作っていました。 棚卸しの対象は自作スキルだけではありませんでした。
この 3 つを、公式ドキュメントの記述と、自分の環境の実測で順番に見ていきます。検証環境は Claude Code v2.1.220 / WSL2 (Ubuntu) / 2026年7月時点です。
用語の整理 (3 分)
先に、この記事で使う言葉を定義します。すでにご存じの方は次の節へ飛んでください。
Agent Skills (スキル)
Claude に手順書を渡しておく仕組みです。SKILL.md という Markdown ファイルを決まった場所に置くと、Claude がそれを「使える道具」として認識します。CLAUDE.md との違いは読み込むタイミングで、CLAUDE.md は常に文脈に載りますが、スキルの本体は使う瞬間まで読み込まれません。だから長い手順書を置いても普段のコストになりません。
SKILL.md の構造
先頭に YAML の frontmatter、その下に本文の手順を書きます。最小構成はこれだけです。
---
name: commit-review
description: コミット前の差分レビュー。「レビューして」「差分見て」で発火させる。
---
# 手順
1. git diff を取得する
2. ...
description
frontmatter の中で、Claude が「このスキルを今使うべきか」を判断する材料になる唯一のフィールドです。本文の手順がどれだけ良くても、description で選ばれなければ 1 行も読まれません。
発火 (はっか)
Claude が自分の判断でスキルを呼び出すことを、本記事では発火と呼びます。公式の用語ではなく、私が運用中に使っている言い方です。/skill-name と自分で打って呼ぶ場合は、発火の判断が要らないので今回の話の対象外です。
壁1: description は、あなたが書いたとおりに届いていない
何が起きているか
公式ドキュメントの「Skill descriptions are cut short (スキルの説明文が途中で切られる)」という節に、こう書かれています。
Claude Code loads a listing of skill names and descriptions into context so Claude knows what's available. The listing always contains every skill name, but if you have many skills, Claude Code shortens descriptions to fit the listing's character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1% of the model's context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text.
（Claude Code は、どんなスキルが使えるかを Claude に知らせるために、スキル名と説明文の一覧をコンテキストに読み込む。一覧には必ず全スキルの名前が入るが、スキルの数が多い場合、Claude Code は一覧の文字数予算に収まるよう説明文を短くする。その結果、リクエストと一致させるために Claude が必要としているキーワードが、削り落とされることがある。予算はモデルのコンテキストウィンドウの 1% に比例する。一覧が予算を超えたとき、Claude Code は呼び出し回数が少ないスキルから順に説明文を落とすので、よく使うスキルは全文が残る）
要点を 3 つに分けます。
- Claude は起動時に「スキル名 + description」の一覧を受け取る。ただしこの一覧には文字数の予算がある
- 予算を超えると、Claude Code が description を勝手に短くする。その結果、あなたが発火のトリガーとして書いたキーワードが消えることがある
- 削る順番は 「呼び出し回数が少ないスキルから」
3 番目が効きます。新しく書いたスキルは、まだ 1 度も呼ばれていません。 つまり削られる列の先頭にいます。書いたばかりのスキルが発火しないのは、初期状態として仕組みに組み込まれているわけです。
「予算」を具体例で
言葉だけだと掴みにくいので、数字で見ます。
Claude Code は起動時に、スキルの名前と説明文を一覧にして Claude に渡します。 この一覧に使える文字数の上限が「予算」です。ここでは仮に 2,000 字とします (根拠は次の節)。
スキルが 5 本、説明文が各 200 字の場合。 合計 1,000 字なので予算に収まります。書いた説明文はそのまま Claude に届きます。 この状態なら、発火しないのは純粋に書き方の問題です。
私の環境は 42 本、平均 334 字、合計 14,062 字でした。 予算 2,000 字に対して 7 倍です。1 万 2 千字ぶんは、そもそも渡っていません。
では、渡らないのはどの部分か。私のレビュー用スキルの説明文は、こう書いてあります。
公開前の成果物 (記事・資料・提案書) の品質レビュー。
「レビューして」だけでなく「辛口で見て」「壊して」「フィードバックして」でも発火させる。
発火させない条件: 新規作成の依頼 / 誤字修正だけの軽微な直し / 内部メモの更新
予算に収まらないと、後ろから落ちて、Claude にはこれだけが届きます。
公開前の成果物 (記事・資料・提案書) の品質レビュー。
この状態で「壊して」と頼んでも、呼ばれません。 「壊して」で発火させるという指定が、まさに削られた部分に入っているからです。
私は「呼ばれないから、もっとトリガーの言葉を足そう」と考えて、説明文を長くしていました。長くするほど予算を超え、足した部分から先に消えます。 逆効果を全力でやっていたわけです。
私はここを、ずっと自分の文章力の問題として扱っていました。
自分の環境で測ってみた
「予算」と言われても、自分が超えているのか分かりません。測りました。
私の環境にはスキルが 42 本あります。全部の description の文字数を合計するスクリプトです。
cd ~/.claude/skills && python3 -c "
import glob, re, os
rows = []
for f in sorted(glob.glob('*/SKILL.md')):
t = open(f, encoding='utf-8', errors='ignore').read()
m = re.search(r'^---\s*\n(.*?)\n---', t, re.S)
if not m:
continue
d = re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:|\Z)', m.group(1), re.S | re.M)
s = (d.group(1) if d else '').strip()
rows.append((len(s), os.path.dirname(f)))
tot = sum(r[0] for r in rows)
print(f'{len(rows)} 本 / 合計 {tot:,} 文字 / 平均 {tot // len(rows)} 文字')
for l, n in sorted(rows, reverse=True)[:5]:
print(f' {l:4} 文字 {n}')
"
結果です。
42 本 / 合計 14,062 文字 / 平均 334 文字
787 文字 docx
761 文字 page-cro
700 文字 ai-seo
680 文字 copywriting
667 文字 content-strategy
合計 14,062 文字。
公式は予算を「モデルのコンテキストウィンドウの 1%」としか書いていません。
コンテキストウィンドウというのは、AI が一度に抱えていられる情報量の上限です。会話の履歴も、読み込んだファイルも、このスキル一覧も、全部ここに載ります。要するに AI の机の広さで、机が広いほど資料を並べておけますが、無限ではありません。上限は使うモデルによって違い、トークン (AI が文章を区切って数える単位) で 20 万というものが標準的です。
その 1% が予算、ということになります。ただし公式は「1%」としか書いておらず、トークン数から文字数への正確な換算式は示されていません。 ここでは 200,000 の 1% = 2,000 文字と読みました。この読み方が正しければ、私の環境は予算の 703% です。 7 倍あります。
念のため書いておくと、これは私の計算であって公式の数字ではありません。自分の環境の正確な値は、推測せず /doctor で確認してください。
/doctor は Claude Code に組み込まれている健康診断のコマンドです。会話中に /doctor と打つだけで実行でき、設定やインストールの不具合に加えて、スキル一覧が実際にどれだけコンテキストを食っているかと、その内訳の上位を出してくれます。何も変更しない読み取り専用の診断なので、気軽に打って大丈夫です。
同じく組み込みの /context を打つと、いま何がどれだけコンテキストを占めているかが項目別に出ます。その Skills 行に、予算を適用した後のサイズが表示されます。つまり /context の数字は「実際に Claude へ渡っている量」で、この記事で私が計算した 14,062 字は「渡す前の量」です。この 2 つの差が、削られた分ということになります。
上位 5 本を見て気づいたこと
さきほどの出力で、文字数の多い上位 5 本を見てください。docx、page-cro、ai-seo、copywriting、content-strategy。
1 本も自分で書いていません。 どこかで見つけて入れたまま、存在自体を忘れていたものです。
自分の環境で仕分けるときは、~/.claude/skills/ の各 SKILL.md を開いて「自分で書いた覚えがあるか」で分けてください。私の場合は自作が日本語、もらいものが英語で書かれていたので、機械的に分けられました。
自作と配布で分けて集計し直しました。
| 種別 | 本数 | description 合計 | 平均 |
|---|---|---|---|
| 自分で書いたもの | 12 本 | 2,418 文字 | 201 文字 |
| 配布されたもの | 30 本 | 11,644 文字 | 388 文字 |
予算の 83% を、自分で書いていないスキルが占めていました。
配布スキルは丁寧に書かれています。だから長い。削る順番は「呼び出し回数が少ない順」です。ここで断定はできませんが、一度も使っていない配布スキルが、たまに使う自作スキルより先に残ってしまう可能性はあります。ただし順番がどうであれ、使っていない配布スキルが予算を占有し続けている事実は変わりません。
Zenn 版では、この現象を「候補が多いと選択の精度が落ちる」と書きました。推測でした。実際は精度の問題ではなく、判断材料そのものが物理的に消えているという、もっと単純な話でした。
対処 1: 使っていない配布スキルを一覧から降ろす
公式に用意されている設定があります。skillOverrides に name-only を指定すると、そのスキルは一覧に名前だけが載り、description が外れます。その分の予算が空きます。
書き先は、全プロジェクト共通なら ~/.claude/settings.json、このプロジェクトだけなら .claude/settings.json です。個人運用なら前者でよいと思います。
{
"skillOverrides": {
"ai-seo": "name-only",
"page-cro": "name-only",
"content-strategy": "name-only"
}
}
name-only にしても消えるわけではなく、/ai-seo と自分で打てば使えます。「たまに使うが、Claude に自動で選んでほしくはない」ものを降ろすのが狙いです。
対処 2: 予算そのものを上げる
skillListingBudgetFraction を上げる方法もあります。0.02 なら 2% です。
{
"skillListingBudgetFraction": 0.02
}
環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で文字数を直接指定することもできます。
ただしこれは、一覧に使うコンテキストを増やすということです。空から湧いてくるわけではありません。私は先に対処 1 で減らす方を勧めます。
対処 3: description の冒頭に主力の用途を置く
description と when_to_use を合わせた文字数は、予算とは別に 1,536 文字で切られます。
公式はここで「主力の用途を先に書け (Put the key use case first)」とだけ述べていて、どちら側から切るかは明言していません。 ただしこの推奨がある以上、後ろ側が落ちる可能性が高い、というのが私の解釈です (未確認)。
つまり、主力の用途を後ろに書くと、そこだけ消えるかもしれません。 私の自作 12 本は最長でも 495 文字だったので今回は該当しませんでしたが、長く書く方は順番に注意してください。
なお when_to_use という、トリガーになる言い回しを別に書けるフィールドがあります。私は 42 本のうち 0 本でしか使っていませんでした。存在を知らなかっただけです。
そのうえで、description の書き方も直す
予算の話をしましたが、description の書き方が効かないわけではありません。予算内に収まっていても、要約文になっていると発火しません。
私のレビュー用スキルは、当初「レビュー」という単語がない場面で呼ばれませんでした。書き直しの前後がこれです。
# Before (要約文になっている)
description: 成果物をレビューし、改善点を指摘する
# After (呼び出し条件のリストになっている)
description: 公開前の成果物 (記事・資料・提案書) の品質レビュー。
「レビューして」だけでなく「辛口で見て」「壊して」「フィードバックして」でも発火させる。
発火させない条件: 新規作成の依頼 / 誤字修正だけの軽微な直し / 内部メモの更新
変えたのは 2 点です。言い換えの語を並べたことと、「発火させない条件」を書き足したこと。
後者は最初、無駄だと思っていました。書かなくても呼ばれないなら同じだろう、と。違いました。トリガーの語を並べていくと、似た言葉を使う別の作業と必ず重なります。「レビューして」はコードにも記事にも使う。そこで境界を書いておかないと、コードのレビュー依頼で記事用のスキルが出てきます。
正直に書くと、この「発火させない条件」を書けているのは自作 12 本のうち 3 本だけです。25% です。Zenn 版では「半分近く」と書きましたが、数え直したら違いました。訂正します。
壁2: 効いているか測っていないスキルは、静かに負債になる
エラーにならないから気づかない
スキルが増えると、古い指示が今の運用と食い違います。数か月前に書いた前提のまま動いて、変な出力が返ってくる。
やっかいなのは、これがエラーとして現れないことです。処理は最後まで走り、出力も一見それらしく見えます。並べて見比べて初めて、古い前提が混ざっていたと分かります。曖昧に書かれたスキルは、無いより悪い状態を静かに作ります。
あり / なしで比べる 3 ステップ
やり方は単純です。同じ依頼を 2 回投げて、出力を並べます。
# 1. 対象のスキルを一時的に退避する
mkdir -p ~/.claude/skills_off
mv ~/.claude/skills/対象スキル名 ~/.claude/skills_off/
# 2. Claude Code を再起動して、いつもの依頼文を投げる → 出力を保存
# 3. 戻して、同じ依頼文をもう一度投げる
mv ~/.claude/skills_off/対象スキル名 ~/.claude/skills/
差が見つからなければ、それは「なくても困らないスキル」というシグナルです。
再起動を挟むのを忘れないでください。 スキルの一覧は起動時に読み込まれるので、ファイルを動かしただけでは反映されません。私はこれで一度、「退避したのに同じ出力が出る」と勘違いしました。
ファイルを動かすのが不安なら、さきほどの skillOverrides に "対象スキル名": "off" を書いて再起動する方法でも同じことができます。こちらは設定ファイルの 1 行を消せば元に戻ります。
なお、この比較そのものを自動化する手段が公式にあります。skill-creator プラグインです。
/plugin install skill-creator@claude-plugins-official
/reload-plugins
インストール後、「このスキルを評価して」と頼むと、テストケースの作成から、あり／なしの比較・採点まで回してくれます。本数が多い方は、手作業より先にこちらを試す方が早いです。 私は今回の実測をしてから存在を知りました。
測ったから直せた例
レビュー用のスキルを比較したとき、あり・なしで出力の量は変わるのに、使い勝手が変わっていないことに気づきました。どちらも問題点を並べて終わっていたからです。
そこで出力の要件を 2 つ足しました。
- 指摘には必ず修正文をセットで出す (「ここが弱い」で終わらせない)
- 採点には及第点との差の内訳を添える (「65点」だけでなく、どの修正で何点戻るか)
これでレビューが「診断書を渡して終わり」ではなくなりました。指摘だけのスキルは、実務では使い物になりません。 直し方まで込みで出す設計にして初めて、次の行動につながります。
「あった方が良さそう」で書いたスキルを、実際の出力で見直したから気づけた差です。
白状すると、42 本のうち全部を測れてはいません。効かせる仕組みを増やす前に、効いているかを確認する習慣の方が先だ、というのが数か月運用しての反省です。
壁3: 増やす前に、線引きを決めておく
スキルは増やすより減らす方が難しい。追加は思いついた瞬間にできますが、統合や削除は「本当に使っていないか」を確認する手間がかかります。だから追加する前の線引きが、後から効いてきます。
私が決めているルールは 3 つです。
-
短い命令形で済むものは CLAUDE.md に書き、詳細な手順書が要るものだけをスキルにする
公式も「CLAUDE.md の一節が、事実ではなく手順に育ってきたらスキルにする」という線引きを示しています -
追加する前に、既存スキルとの重複を検索する (
grep -rl "キーワード" ~/.claude/skills/) - 本数の上限を決めて、超えたら統合するか退避する
3 番目の意味が、今回の実測で変わりました。以前は「自分の管理コストを抑えるため」だと思っていました。今は違います。本数の上限は、文字数予算の上限とほぼ同じものです。上限を決めないと、予算を超えた分だけ description が削られ、発火が静かに悪化していきます。
そして予算を食っているのが自分で書いていない配布スキルだったというのが、今回いちばん効いた発見でした。棚卸しの対象は、自作スキルだけではありません。
明日から使えるチェック 3 つ
-
/doctorを実行して、スキル一覧のコンテキストコストを見る。 内訳の上位に、自分で書いていないスキルが並んでいないか - スキル 1 本を退避して、同じ依頼を 2 回投げてみる。 出力に差がなければ、それは消してよいスキル
-
descriptionを 1 本開いて、要約文になっていないか確認する。 なっていたら、言い換えの語と「発火させない条件」を足す
冒頭に書いた「書いた description が届いていない」は、1 と 3 で確認できます。2 は、届いた後に効いているかの確認です。
作る労力はスキル 1 本ぶんですが、効かせる労力は本数ぶん、ずっと続きます。だから増やす前に、この 3 つを回す方が先でした。
「ここまで読めば自分でも調整できそう」と思われたかもしれません。実際、この記事の 3 つのチェックだけで、発火しない問題の大半は当たりが付きます。
残るのは「そもそも何を Claude に任せるか」です。任せる業務が決まっていないと、スキルは書きようがありません。私がいま任せているのは約 50 案件の進捗管理と催促で、そこで実際に動かしているプロンプト 4 本の全文・コード一式・セットアップ手順・練習用のダミー案件 20 件は、note の実践パッケージ (¥1,480〜) にまとめています。スキルの話ではなく、その手前の「何を任せるか」を実物で見たい方向けです。
関連記事: Claude Codeに毎回していた背景説明を、Obsidian連携10分でなくした
参考: Claude Code 公式ドキュメント — Extend Claude with skills
🔍 moname_ai — Claude を本業で使い倒した実測記録を書いています。続きは Bluesky (@moname-ai.bsky.social) で。
📢 8/29(土) にオンライン勉強会をやります
記事で書いている「AI に任せる仕組み」の実物を、40 分でお見せします。50 案件の進捗催促を Slack・スプレッドシート・cron で自動化した構成とデモ、うまくいかなかった部分も含めて話します。オンライン・無料・定員 20 名です。