この記事は2026年3月に書いたものです。手順と測り方は2026年8月に自分の環境で実測し直して差し替えました。
Anthropicが公式で「The Complete Guide to Building Skills for Claude」というPDF（33ページ）を出した。
中身を読んで、自分のスキル構成に反映した。結果から言うと、SKILL.mdのトークン消費が約40%減った。体感でもレスポンスが速くなった。
私が何をしている人で、何に困っていたか
先に前提を書きます。ここが無いと、以下の数字が誰の環境の話なのか分からないからです。
私はプログラミングができません。AIに指示を出して、記事を書いたり小さな道具を作ったりしています。使っているのは Claude Code という、AIがコマンドを実行しながら開発を手伝ってくれる道具です。
その Claude Code には スキル という仕組みがあります。「この作業のときはこう進めろ」という手順書を SKILL.md というファイルに書いて置いておくと、AIがその手順に従ってくれる、というものです。便利なので増やし続けて、80個になりました。
そこで怖くなったのが、増やした分だけAIに読ませる文章が増えて、遅く高くなっているのではないかということでした。ただ、どこを削れば効くのかが分かりません。手当たり次第に本文を短くしても、効いている手応えがない。
公式ガイドを読んで分かったのは、削る場所を丸ごと取り違えていたということでした。設定ファイルや手順書がふくらんで同じ不安を持っている人には、そのまま使える話だと思います。
:::details 初心者向け: トークン消費とは
AIに文章を送ると、AIはその文章を「トークン」という小さな単位に分割して処理します。日本語だと1文字が1〜3トークンくらい。送る文章が長いほどトークンを多く消費し、処理時間もコストも増えます。つまり「トークン消費を減らす」＝「AIに読ませる文章量を減らして、速く安くする」という意味です。
:::
原文（英語PDF）: The Complete Guide to Building Skills for Claude
以下は、実際に自分の環境で適用して効いた部分です。削る場所の見つけ方と、効いたかどうかの測り方を書きます。
どこが「常駐」しているのかを取り違えない
削減で最初につまずくのはここです。SKILL.md の本文は、毎セッション読み込まれているわけではありません。
常に載っているのは前付けの name と description だけで、本文はそのスキルが実際に呼ばれた時に初めて読まれます。これが Progressive Disclosure（段階的な開示）の実体です。
自分の環境で測ると、比率がはっきりします（2026-08-02、スキル80個での実測）。
| 文字数 | 割合 | |
|---|---|---|
常駐（name ＋ description） |
9,074字 | 2.4% |
| 遅延（本文・呼ばれた時だけ） | 361,574字 | 97.6% |
つまり 37万字あっても、毎回のセッションが背負っているのは9千字だけです。
ここを取り違えると、本文をいくら削っても常駐コストは1文字も減りません。削る的は description です。
自分の description を測る
依存するものはありません。この1行で長い順に出ます。
awk 'FNR==1{f=FILENAME; n=0} /^---$/{n++; next} n==1 && /^description:/{sub(/^description:[ ]*/,""); gsub(/^"|"$/,""); split(f,a,"/"); print length($0), a[length(a)-1]}' ~/.claude/skills/*/SKILL.md | sort -rn | head
自分の環境での出力です。
445 xlsx
428 doc-coauthoring
399 frontend-design
378 playwright
362 docx
329 internal-comms
324 algorithmic-art
289 canvas-design
description の中央値は52字でした。それに対して上位は400字を超えています。
80個のうち200字を超えていたのは19個。その19個だけで常駐9,074字の66%を占めていました。 この19個を200字へ揃えるだけで2,161字、常駐の24%が減ります。
長い description は、たいてい「いつ使うか」の条件を書き足しているうちに膨らみます。判定に本当に要るのは、他のスキルと区別できる最小限です。詳しい使い分けは本文（Layer 2）へ、実行時にしか要らない手順やテンプレートは参照ファイル（Layer 3）へ下ろします。本文は長くても常駐しません。
削る理由はもう1つあります——長すぎると、書いた内容が届きません
ここまでは費用の話でしたが、もうひとつ理由があります。手元の Claude Code（2.1.233・Linux/WSL2）の本体を調べると、スキル一覧には2つの上限が実在します。設定スキーマの説明文をそのまま引きます（3文目まで含めて全文です）。
| 設定 | 既定 | 本体の説明文 |
|---|---|---|
skillListingMaxDescChars |
1536字 | Per-skill description character cap in the skill listing sent to Claude (default: 1536). Descriptions longer than this are truncated. Raise to opt in to higher per-turn context cost. |
skillListingBudgetFraction |
0.01（1%） | Fraction of the context window (in characters) reserved for the skill listing sent to Claude (default: 0.01 = 1%). When the listing exceeds this, descriptions are shortened to fit. Raise to opt in to higher per-turn context cost. |
1つめは1スキルあたりの上限で、超えたぶんは末尾から切り落とされます。2つめは一覧全体の取り分です。どちらも settings.json で上げられます（引用の最後の一文がそれです）。ただし一覧は毎ターン送られるので、上げたぶんだけ毎ターンの費用が増えます。先に削るほうが安いのは、そのためです。
枠に収まらなくなった時の挙動が、少し意外でした。1件ずつ均等に短くするのではなく、入るものは説明文つきのまま残し、あぶれたものは説明文ごと落として名前だけにします。 落ちたスキルは、名前しかモデルに見えません。
自分が当たっているかは、/context で1分で分かります
claude -p "/context"
返ってくる表に Skills の行（一覧全体のトークン数と割合）があり、その下にスキル別の内訳が並びます。400字書いた description のスキルが極端に少ないトークン数で載っていたら、一覧へ入る前に落とされています。
自分の環境で測った結果も書いておきます。自作のスキル80個・Opus 5（窓 800k）で Skills は 5k トークン・0.6%。取り分の1%に届いておらず、445字の description のスキルも約150トークンでそのまま載っていました。落ちているものはありません。
取り分は窓に比例します。既定の 200k の窓なら 200,000 × 4 × 0.01 で 8,000字ぶん、800k の窓なら 32,000字ぶんです（4 は本体が使っている1トークンあたりの文字数の目安）。つまり同じスキルの数でも、窓の狭いモデルで当たり、広いモデルでは当たらない、ということが起こります。
上の表の「常駐 9,074字」は 2026-08-02 に測った name ＋ description の合計です。一覧はこれに1件あたり記号と改行で5字ぶんが乗り、description 自体もこの16日で少し伸びたので、今日あらためて80個で数え直すと約10,028字。800k の窓の取り分（32,000字）には収まっていました。
この上限そのものと、発火しない時の切り分けの順番は別の記事に詳しく書いています（無料）。
削減が効いたかを測る
自分の環境での測り方:
claude -p "ok" --output-format json | jq '.usage'
返り値に input_tokens / cache_creation_input_tokens / cache_read_input_tokens / output_tokens が入ります。SKILL.md を削る前と後で同じプロンプトを打ち、cache_creation_input_tokens の差を見れば、削減が自分の環境で実際に効いたかを確かめられます。
実際に打つとこう返ります（2026-08-02、Opus 5 での実測値）。
{
"input_tokens": 13,
"cache_creation_input_tokens": 21512,
"cache_read_input_tokens": 212933,
"output_tokens": 2420
}
input_tokens が13しかないのに cache_read_input_tokens が212,933ある、というのがポイントです。毎ターンの実費のほとんどは、その場で打った文字ではなく、常駐している設定の読み直しで決まります。 SKILL.md はまさにその常駐側にいるので、ここを削ると全ターンに効きます。
この例では cache_creation / (cache_creation + cache_read) は9.2%でした。この比率が跳ね上がっている時は、削減の効果よりキャッシュの作り直しの方が支配的になっている合図です。
2026-08-02 訂正
ここには以前、claude /usage --json と claude --no-mcp /usage --json を使う手順を書いていました。どちらも実在しません。 打つと error: unknown option '--json' が返りますし、--no-mcp というオプションはそもそもありません。自分で打ち直して、上の動く形に差し替えました。
対話中の /usage は実在しますが、返るのは利用枠の消費率（Current session: 8% used のような表示）で、キャッシュの内訳は返りません。動かない手順を長いあいだ載せていました。
削っても減らない時に疑うところ
SKILL.mdを40%削減しても、別の経路でトークンが増えている可能性があります。2026-04-24にsurfaceしたIssue #52942は、Claude Codeがビルトインツールのschema定義を毎ターンsystem promptに展開する挙動を報告しています。ユーザー側でSkillsやCLAUDE.mdをいくら削っても、ツールスキーマ由来の固定コストは残ります。
この削減を、自分の SKILL.md で今すぐ測れます
記事の40%削減は、自分の SKILL.md で実際に測ると実感が変わります。SKILL.md トークン自己診断（無料・ブラウザの中だけで完結） に自分の SKILL.md を貼ると、毎セッションで常駐するトークンのコストと、3層化（Progressive Disclosure）した後の Layer1 だけの削減の見込み（%）を実測し、コードや設定のブロック・表・API 仕様・長い節といった「重い塊」を検出して、どこを Layer2 / Layer3 へ動かせばよいかを具体的に示します。貼った SKILL.md は外部へ送信されません（計測なし・サーバー送信なし）。
この記事で削ったのは「常駐」のコスト——毎セッション必ず読み込まれる分です。同じ主題の続きが2冊あります。
- 上で触れた「長すぎると届かない」ほうを追い込むなら Claude Code Skills 実践レシピ集（¥500、はじめにと第1章は無料）。第11章が、上限の実在を本体のバンドルで確かめたうえで、
settings.jsonでの上げ方（上げると毎ターンの費用が増えるトレードオフ）と、発火しない時の切り分けの順番を書いています。ほかに10個のレシピと、発火を確かめるトリガーテストの手順が入っています - 常駐ではなく「使うたび」の消費——会話の本体・サブエージェント・出力まで含めて減らすなら Claude Code のトークン消費を半分にする本（¥2,500、第1章まで無料）
ここまでの手順で、常駐のぶんは減らせます（自分の環境では40%減りました）。それでも残るのが「うちの消費の内訳が、これでは説明できない」という状態です。自分のログを156セッション分そのまま数え直したときは、いちばん大きな浪費のパターンが、自分が本に載せた56件の症状のどれにも当てはまりませんでした。
その実物を監査の見本として全文公開しています（無料・登録不要）。自分のログに同じ読み方を当ててほしい人向けに、48時間以内に書面で返す有償の監査（¥3,980）も受け付けていますが、先に /cost と ccusage を試してください。「いくら使ったか」はそれで無料で分かります。分からないのは「自分のどの癖がその金額を作ったか」のほうだけです。