エージェントに見えていなかったスキル

84個のスキルをインストールし、その84個すべてが動いているものと思い込んでいました。実際には5つが動いていませんでした。swiftui、testing-philosophy、typeset、web-performance、update-shortcuts-guide は、ディスク上のファイルには申し分のない description が書かれているにもかかわらず、名前だけで description の付かない状態でモデルに届いていたのです。description こそが ルーティングのシグナルである以上、description のないスキルにはルーティングできません。この5つが自動起動する可能性はそもそもなく、しかもそれを知らせてくれるものはどこにもありませんでした。エラーも警告もログ行もありません。見つけたのは偶然で、原因を証明できた唯一の理由は、修正した瞬間に目の前で症状が反転したからです。 {.answer-block}

TL;DR

• スキルの description は毎ターンのコンテキストに読み込まれ、固定の文字数バジェットを共有します。これを超えると description は黙って削られます。¹²
• インストール済みは84個、うち82個が description を持ち、合計21,848文字でした。5つは名前だけが届き、description が欠けていました。ディスク上ではその5つはそれぞれ206〜336文字です。
• どの5つが削られたのかを説明できるファイル属性はありませんでした。description の長さ、ファイルサイズ、YAML の書式、name とディレクトリ名の不一致、更新日時のいずれも、削られた側と残った側で重なっていたのです。
• 74個の description を書き直し、合計9,885文字にしました。5つすべてがセッションの途中で、同じ会話のなかで description 付きのまま復活しました。仮説、介入、確認です。
• 正確なバジェットは文書化されておらず、現在も見解が割れています。Anthropic には、この割合が固定の200Kベースラインに対して計算され、1M のコンテキスト拡張が無視されているという報告のオープンな issue があります。³⁴
• 収まるようにした書き直しのルールはこうです。description の唯一の仕事は「いつ呼び出すべきか」に答えること。手順、思想、ファイルパスは本文に属し、本文は呼び出されたときにだけ読み込まれます。

エラーメッセージのない障害

ハーネスのバグはたいてい自分から名乗り出ます。フックが非ゼロで終了する、MCP サーバーが起動を拒む、ツール呼び出しがスタックトレースを返す。description のバジェットはそのどれもしません。ディスク上にあるものより短いリストを静かにモデルへ差し出すだけで、その結果として現れる症状はすべて、配管の問題ではなくモデルの問題に見えてしまいます。

気づいたきっかけは、ファイルシステムではなく自分のコンテキストウィンドウを読んだことでした。スキル一覧を眺めていると、5つのエントリーだけが名前しかなく、その後ろに何もありません。ほかのエントリーはどれも名前と一文を持っています。そこでファイルを開いて確かめました。

swiftui                    HAS  322 chars on disk -> DROPPED in context
testing-philosophy         HAS  291 chars on disk -> DROPPED in context
typeset                    HAS  248 chars on disk -> DROPPED in context
web-performance            HAS  206 chars on disk -> DROPPED in context
update-shortcuts-guide     HAS  336 chars on disk -> DROPPED in context

その結果は、スキルが遅い、あるいは間違っているよりも深刻です。エージェントはスキルを呼び出すかどうかを description を読んで決めます。description を取り去れば、ルーティングが劣化するのではなく、ルーティングそのものが消えます。スキルはインストールされ、有効で、それでいて到達不能です。swiftui は私の iOS 26 パターンのスキルなので、これまで走らせた Swift のセッションはすべて、それなしで飛んでいたことになります。

Anthropic には同じ障害を記述したオープンな issue があり、そのひとつは「Skill description budget silently truncates routing information, causing skill routing failures」という題です。² つまりこれはローカルな設定ミスではなく、既知のバグということになります。知れたのは有益でしたが、自分のどのスキルが影響を受けているのかを突き止める役には立ちませんでした。

安易な答えを潰す

誘惑されたのは、メカニズムを推測してそのまま直してしまうことでした。私はまず推測を反証しにかかりました。「5つのスキルが壊れている」と「この理由で5つのスキルが壊れている」は、まったく別の主張だからです。

ファイルレベルの何らかの性質がスキルを削除対象に選んでいるのなら、削られた側と残った側は測定可能などこかで違っているはずです。そこで比較しました。

両者を分けるものは何もありませんでした。削られた description が最長だったわけではなく、ファイルが際立って大きかったわけでもなく、YAML のスタイルはどちらのグループにも混在し、更新日も同じ範囲に散らばっています。アルファベット順の位置という説明も外れました。swiftui より後ろに並ぶスキルは description を保っていたからです。

この時点で誠実な立場は、「再現する症状はあるが、メカニズムはない」というものでした。だからそのとおりに書き留め、理屈ではなくテストを探しにいきました。

テスト

効いているのが合計バジェットなら、どのファイルを削るかにかかわらず、合計を減らせば削られた description は戻るはずです。この予測は反証可能で、しかも安上がりです。

74個の description を書き直し、合計を21,848文字から9,885文字にしました。それまで見えていなかった5つのスキルが、同じセッションのなかで、再起動もせずに description 付きで戻ってきました。

実験はこれで全部です。予測ひとつ、介入ひとつ、確認ひとつ。削除は個々のファイルの性質ではなく合計サイズの関数であり、だからこそファイル単位のどの属性でも2つのグループを区別できなかったのです。

痕跡を残さないバグにも、反実仮想は残ります。障害を観察して原因を見つけられないなら、変数をひとつ変えて、障害がそれに追随するかを見ればよいのです。

自分が確立できなかったことについては正確に書いておきます。正確なバジェットは分かりませんし、出典を示せない数字を公表するつもりもありません。公式ドキュメントはこの上限に触れていません。⁵ コミュニティの計測は、実用上の上限をスキルのメタデータ合計で15,500〜16,000文字あたりに置き、XML タグ、スキル名、location フィールドによる1エントリーあたり約109文字のオーバーヘッドを指摘しています。生の description 文字数では、そのどれも捉えられません。⁶ スキルが84個あれば、このオーバーヘッドだけで約9,156文字になります。一方で Anthropic のコントリビューターは、バジェットの割合が固定の200Kベースラインに対して計算され、1M のコンテキスト拡張を無視すると報告しています。同じマシン上の2つのセッションが、異なるバジェットを受け取りうるということです。³⁴

この発見を最初に書き上げたとき、私は自分の環境が「バジェットを119%超過している」と書きました。検証していない仮定（1M ウィンドウの1%）に実測値を掛け合わせ、裏づけのない自信ありげな数字を作り出していたのです。観測された事実は生き残ります。21,848文字では5つの description が落ち、9,885文字ではひとつも落ちませんでした。パーセンテージは生き残らず、そもそも書かれるべきではありませんでした。

description の唯一の仕事はルーティング

12,000文字を削ると聞くと破壊的に響きます。そうではありませんでした。それらの description に入っていた内容の大半は、そもそもルーティングの仕事をしていなかったからです。

私の jiro スキルが掲げていたのは、686文字のこれです。

コード品質と職業的な誇りのための職人（Shokunin）の craftsmanship 哲学。機能の実装、コードのリファクタリング、テストの記述、作業のレビュー、あるいは FastAPI/Python、Swift/SwiftUI、HTMX フロントエンド、インフラコードにまたがる自明でない変更の作業時に起動します。3つの中核的な哲学を埋め込んでいます。職人（見えない細部における卓越）、おもてなし（技を通じた奉仕）、Rick Rubin（創造性の媒介と蒸留）。中心となる判断のゲートは Evidence Gate（品質についての感想ではなく、品質の証拠を出すこと）。使用する場面：機能の構築、リファクタリング、テスト、コードレビュー、バグ修正、あるいは完了を報告する前に品質の証拠が求められるあらゆる作業。

そのうちおよそ500文字は、スキルに何が入っているかの説明です。開くべきかどうかを判断する助けにはなりません。置き換えたものは126文字です。

コード品質のための職人気質と証拠の基準。実装、リファクタリング、テスト、レビュー、バグ修正のときに使用。

トリガーとなる語も同じ、ルーティングの挙動も同じ、コストは5分の1。思想が消えたわけではありません。それは本文に住んでいて、本文はスキルが実際に走るときにだけ読み込まれます。毎ターンそれに支払っても、得られるものは何もありませんでした。

同じパターンが全体に繰り返されていました。9個の update-*-guide スキルは、ソースをスキャンし、コピーを同期し、翻訳を走らせるといったほぼ同一の定型文を3,024文字ぶん抱えていました。それぞれおよそ115文字に畳んでも、正しくルーティングされます。各スキルを区別するのは、共有しているパイプラインではなく、どのガイドを更新するかだからです。

働いたルールは3つです。

1. トリガーは残し、説明は削る。 名前、スラッシュコマンド、ユーザーが実際に打ちそうな語は残します。内部手順の説明は落とします。
2. ファイルパスは本文に置く。 パスは、いつ何かを呼び出すべきかをモデルが判断する助けになりません。
3. 共有の定型文は純粋なオーバーヘッド。 9つのスキルが同じ一文を言うなら、その一文はどれ一つ区別しません。

第二の税：呼ばれずに作用する description

削り込むことで、より微妙なコストが露わになりました。私の description のうち11個、合計3,808文字が命令形の言葉を抱えていたのです。ALWAYS、NEVER、MUST、PROACTIVELY、BEFORE。distribute は NEVER と言い、no-shortcuts は ALWAYS と言い、git-custody は BEFORE と言っていました。

これらの語は、スキルが走るかどうかに関係なく毎ターンのコンテキストに座り続けます。命令として書かれている以上、命令として読まれるのです。そしてモデルには、description を不活性なカタログ文として扱いながら、同じ言い回しのシステム指示は拘束力あるものとして扱う、という信頼できる方法がありません。

最近の研究がこの効果に名前を与えています。「The Regression Tax」は、2つのオフィス自動化ベンチマークと3つのハーネススタックにまたがるおよそ6,000回の実行で計測され、skill description osmosis（スキル description の浸透）を特定しました。呼び出されていなくても、コンテキストに存在するだけでスキルがエージェントの挙動を変えてしまう現象です。¹ 主要な発見は、最良のスキルは多くを得ることよりも劣化が少ないことで勝っており、スキルは手順の指示に過剰投資する一方で、グラウンディングと検証への投資が足りていない、というものでした。

本番の証拠は理論より先に届いていました。Anthropic は v2.1.215 で、同梱の /verify と /code-review スキルの自動起動を撤回し、明示的な呼び出しのみに変えています。⁷ 2つのリリース後には /deep-research も自己起動をやめました。⁸ どちらも重量級のスキルで、頼まれてもいない実行のコストが見返りを上回っていたのです。これはベンダー自身が現場で観測した浸透であり、description を書き直すのではなく起動を取り除くことで是正されました。

つまり肥大した description は二重にコストを払わせます。ほかのスキルがルーティングに必要とするバジェットを食い、誰も頼んでいない挙動上の圧力をかけるのです。どちらのコストも、そのスキルが何も貢献していないターンに降りかかります。

居心地の悪い部分：本文もまた統治しないかもしれない

「本文に移せ」というのは私がいま出したアドバイスですが、そこには声に出して言っておくべき前提があります。呼び出し時にエージェントが読み込む手順は、実際にエージェントの振る舞いを統治する、という前提です。新しいベンチマーク研究は、この前提が聞こえるほど強くないことを示唆しています。

HANDBOOK.md はまさにそれを試しました。65のタスク、20〜124ページのポリシー文書、模擬企業のなかでメール、チャット、カレンダー、コマースをまたいで働くエージェント、そして824のプログラム的な採点基準。30あるモデル構成のうち最良のものでも試行の36.2%しか合格せず、フロンティア構成のほとんどは25%を下回りました。⁹

名指しされた失敗のモードが、ここでは重要です。エージェントは、もっともらしい環境内のリクエストに既定のポリシーを上書きさせてしまいます。必要なチェックを実行しておきながら、その結果に反する行動をとります。長い時間軸のなかでルールの細部を失います。どれも検索の失敗ではありません。文書はずっと利用可能だったのです。

だから私のルールの誠実な版は、「description はルーティングし、本文は説明する」よりも狭くなります。手順を description の外へ動かすことは依然として正しい。ほかのスキルがルーティングに必要とするバジェットを取り戻し、呼ばれていないテキストが挙動を操るのを止めるからです。どちらも本物の利得であり、どちらも本文がうまく統治することに依存していません。それが買ってくれないのは、移した手順が守られるという確信です。124ページのハンドブックと3,000語の SKILL.md 本文は、同じ曲線の上に乗っています。

実務上の読みはこうです。本文の長さをコストとして扱い、無料の駐車場だと思わないこと。あるルールが本当に守られなければならないなら、description はその置き場所として間違っており、長い本文もほんの少しましなだけです。強制は決定的な場所（フック、パーミッションのルール、テスト）に属するのであって、ほかのことをしながら覚えていてくれとモデルに頼む散文のなかにはありません。

自分の環境を監査する

まずセッションの中から始めます。/context を実行すると、除外されたスキルがあるかどうかが報告されます。⁵ 除外が示されたなら、問題は確定で、診断はそこで終わりです。

私がそこから始めなかった理由には学ぶところがあります。私の5つのスキルは除外されていたのではなく、名前は無傷のまま description だけを剥がされて届いていました。これはエントリーが丸ごと消えるよりも静かな障害で、同じようには表面化しないかもしれません。ですからいずれにせよ、ファイルシステムと突き合わせて検証してください。チェックにシェル以外の道具は要りません。

python3 - <<'PY'
import os, re, glob
rows = []
for f in glob.glob(os.path.expanduser('~/.claude/skills/*/SKILL.md')):
    name = os.path.basename(os.path.dirname(f))
    fm = re.match(r'^---\s*\n(.*?)\n---\s*\n', open(f, encoding='utf-8', errors='replace').read(), re.S)
    if not fm:
        continue
    d = re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:|\Z)', fm.group(1), re.S | re.M)
    if not d:
        continue
    desc = ' '.join(d.group(1).split()).strip('"\'').lstrip('|').strip()
    rows.append((len(desc), name))
rows.sort(reverse=True)
print(f'{len(rows)} skills, {sum(r[0] for r in rows)} description chars')
for length, name in rows[:15]:
    print(f'  {length:4d}  {name}')
PY

そのうえで、出力とモデルが実際に受け取ったものを比べます。この2つの差こそが、今回の発見のすべてです。コンテキストの中にスキルが名前だけで現れ、後ろに一文もないなら、そのスキルはインストール済みで、かつ到達不能です。

監査から3つの習慣が導かれます。

長いものだけでなく、新しいスキルはすべてバジェットに数える。 1エントリーあたりのオーバーヘッドは description の長さに関係なく付いてくるので、10個目の90文字のスキルは90文字より高くつきます。

スキルを追加したら数え直す。 安全なマージンは示せません。上限は文書化されておらず、割合の計算方法によって変わると報告されているからです。³⁴ 仮定の上に載った計算上の余裕よりも、経験的なチェックのほうが優れています。まさにその誤りを私は犯しました。

削る前にスナップショットを取る。 私のスキルディレクトリの大半は git の管理外で、7つはリポジトリですらないディレクトリへのシンボリックリンクだったため、git add は「beyond a symbolic link」と言って受けつけませんでした。私はまず、元の description をすべて JSON ファイルに書き出しました。検証していないバージョン管理はバックアップではありません。

要点

• description のないスキルは劣化しているのではなく、到達不能です。 description がルーティングの判断のすべてを担っています。
• この障害は構造上、静かです。 エラーも警告もログもありません。まず /context で除外の警告を確認し、次にコンテキストの一覧をファイルシステムと突き合わせてください。剥がされた description は、消えたエントリーよりも静かだからです。
• 削除を決めるのは合計サイズであり、ファイル単位の性質ではありません。 どのスキルが description を失うかを、個々のファイルの属性は予測できませんでした。
• 観察で分からないなら、介入する。 障害を調べてメカニズムを見つけることはできませんでした。合計を変えて障害が反転するのを見ることで、一手で証明できたのです。
• description はルーティングし、本文は説明する。 description のうちいつ呼び出すかの判断を助けない部分は、毎ターン支払わされ、何も稼ぎません。
• description の中の命令形は、呼ばれずにあなたに作用します。 ALWAYS や NEVER はカタログから挙動を操ります。これが計測された浸透効果です。¹
• 出典を示せないパーセンテージを公表しない。 私自身の最初の書き上げは、実測値に当て推量のバジェットを掛け、自信ありげで間違った数字を生みました。

よくある質問

Claude Code のスキルが起動しないのはなぜですか

モデルがその description を実際に見られているかを確認してください。スキルの description は毎ターンのコンテキストに読み込まれ、固定の文字数バジェットを共有します。これを超えると description は黙って落とされ、エラーも警告もログ行も出ません。私の84個のスキルのうち5つは、ディスク上のファイルには申し分のない description があるにもかかわらず、名前だけでモデルに届いていました。description のないスキルにはルーティングできません。¹²

Claude Code のスキル description のバジェットはどれくらいですか

正確なバジェットは文書化されておらず、現在も見解が割れています。出典を示せない数字を公表するつもりはありません。私が計測したのはこれです。description 合計21,848文字では5つの description が落ち、9,885文字ではひとつも落ちませんでした。コミュニティの計測は実用上の上限を15,500〜16,000文字あたりに置き、1エントリーあたり約109文字のオーバーヘッドがあるとしています。また Anthropic のコントリビューターは、バジェットの割合が固定の200Kベースラインに対して計算されると報告しています。³⁴⁶

どのスキルが description を失ったかを監査するには

まずセッションの中で /context を実行します。除外されたスキルがあるかどうかを報告してくれます。そのうえで、それでもファイルシステムと突き合わせて検証してください。私の5つは除外されていたのではなく、名前は無傷のまま description だけを剥がされて届いていたからです。これはエントリーが丸ごと消えるよりも静かな障害です。SKILL.md のフロントマターにある description の文字数を合計し、そのリストをコンテキストの一覧が実際に示しているものと比べてください。⁵

スキルの description と本文には、それぞれ何を書くべきですか

description の唯一の仕事は、そのスキルをいつ呼び出すべきかに答えることです。トリガーとなる語、名前、ユーザーが実際に打つスラッシュコマンドは残し、手順、思想、ファイルパスは本文へ移してください。本文は呼び出されたときにだけ読み込まれます。私の jiro の description は686文字から126文字になりましたが、ルーティングの挙動は同じでした。そのうちおよそ500文字は、スキルに何が入っているかを説明していただけだからです。

スキルが一度も走らなくても、description は挙動に影響しますか

はい、それが第二の税です。私の description のうち11個は ALWAYS、NEVER、MUST、PROACTIVELY、BEFORE を抱えていました。これらは毎ターンのコンテキストに座り、命令として書かれている以上、命令として読まれます。「The Regression Tax」はこの効果を skill description osmosis と名づけました。呼び出されていなくても、コンテキストに存在するだけでスキルがエージェントの挙動を変えてしまう現象です。¹

参考文献