Claude Skillを自作していて、SKILL.md の description をどこまで詳しく書いてよいのか迷ったことはないでしょうか。答えははっきりしています——1,024文字が上限で、それを超えると切り捨てられます。しかもこの SKILL.md description の上限は、Anthropic自身の公式スキル集ですら守られていませんでした。公式19スキルを公式バリデータにかけたところ、1本が不合格になります。
quick_validate.py で検査した結果。claude-api のみ上限超過（2026-08-24 本サイト実測）- ・description は1,024字上限。超えた分は切り捨て（truncated）。公式バリデータは不合格を返す
- ・name は64字上限かつ kebab-case（
^[a-z0-9-]+$）。先頭末尾のハイフンと連続ハイフンも不可 - ・名前に
claude/anthropicは使えない（アップロード型カスタムスキルの検証。実際に公式スキルが改名された） - ・公式19本中1本が不合格——
claude-apiが1,068字で44字オーバー - ・Anthropic自身が「精度を犠牲にしてでも短くしろ」と書いている。理由は全クエリに常駐するから
- ・実務換算：1,024字は常駐約300トークンの天井に相当（本サイト実測の3.3〜3.5字/トークンで換算）
Claude Code本体の設定・運用まわりを先に押さえたい方は、Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きにまとめてあります。
SKILL.md descriptionの1024字上限——まず数字から確認する
Agent Skillsの仕様書そのものは agentskills.io/specification に移管されていますが、実際に何が弾かれるかは Anthropic が公開しているバリデータのコードを読むのが最も確実です。anthropics/skills リポジトリの skills/skill-creator/scripts/quick_validate.py がそれにあたります。
このスクリプトが機械的に検査している条件を、コードから抜き出すと次のようになります。
| 対象 | ルール | 違反時のメッセージ |
|---|---|---|
name |
kebab-case のみ（^[a-z0-9-]+$） |
should be kebab-case (lowercase letters, digits, and hyphens only) |
name |
先頭・末尾のハイフン、連続ハイフン（--）を禁止 |
cannot start/end with hyphen or contain consecutive hyphens |
name |
64文字以内 | Name is too long (N characters). Maximum is 64 characters. |
description |
山括弧（< >）を含められない |
Description cannot contain angle brackets (< or >) |
description |
1,024文字以内 | Description is too long (N characters). Maximum is 1024 characters. |
compatibility（任意） |
500文字以内 | Compatibility is too long (N characters). Maximum is 500 characters. |
quick_validate.py の実装より）「1,024文字を超えたらどうなるのか」については、同じ skill-creator に同梱されている improve_description.py のプロンプト本文が答えています。「1024文字のハードリミットがある——それを超えた description は切り捨てられる（truncated）ので、余裕をもって下回れ」。つまりエラーで止まるのではなく、黙って途中で切られる経路も存在するということです。frontmatterを長く書いたのに発動しない、という症状に心当たりがあるなら、まず文字数を数えてみる価値があります。
もう1つ、実務上まぎらわしい点を先に潰しておきます。この1,024字は「文字数」であってトークン数ではありません。日本語で description を書いた場合、同じ1,024字でも英語よりトークン換算では重くなる傾向があります。逆に上限判定そのものは文字数で行われるため、英語で書けば同じ字数により多くの情報を詰められるという非対称があります。公式スキルの description がすべて英語で書かれているのは、多言語での発動を狙う以上に、この密度の問題があるからだと考えられます（この解釈自体は公式に明示されたものではなく、本サイトの推測です）。
① 何ができる：自作スキルが配布・アップロードの検証を通るかを、公式バリデータで事前に判定できる。② 何を解決する：「書いたのに発動しない」「アップロードで弾かれる」の原因切り分け。③ 何を代替できる：仕様書を読んで自分でチェックする手間。ルールはコードに書かれているので、コードを走らせるほうが速く確実。
公式19スキルをAnthropic公式バリデータにかけたら1本落ちた
ルールがわかったので、Anthropic自身の公式スキル集がそのルールを守っているかを検査しました。リポジトリをcloneし、同梱の quick_validate.py を19本すべてに走らせます。
git clone https://github.com/anthropics/skills.git && cd skills
for d in skills/*/; do
printf "%-24s " "$(basename "$d")"
python3 skills/skill-creator/scripts/quick_validate.py "$d"
done
結果は 18本が Skill is valid!、1本だけが不合格でした。
claude-api Description is too long (1068 characters). Maximum is 1024 characters.
claude-api の description は1,068文字で、上限を44文字超過しています。19本の中で最も長い description であり、同時に唯一の不合格でもあります。
| スキル | description字数 | 上限までの残り | 判定 |
|---|---|---|---|
| claude-api | 1,068 | -44 | 不合格 |
| academy-guide | 992 | 32 | 合格 |
| discernment-nudge | 983 | 41 | 合格 |
| xlsx | 948 | 76 | 合格 |
| docx | 835 | 189 | 合格 |
| pptx | 732 | 292 | 合格 |
| 437 | 587 | 合格 | |
| skill-creator | 319 | 705 | 合格 |
| webapp-testing / frontend-design | 204 | 820 | 合格 |
上位4本が900字を超えており、上限に対する余裕は数十字しかありません。academy-guide の残り32字、discernment-nudge の残り41字というのは、一文足したら超える距離です。公式スキルですら上限ぎりぎりの運用をしている、と読むべきでしょう。
超過した44文字には何が書かれているか
claude-api の description を1,024字で切ってみると、失われるのは末尾のこの部分です。
"if no provider named — don't Read the file)."
前後の文脈を補うと、これは「クエリでプロバイダが示されていない場合は、ファイルを読む前にまず grep を走らせよ」という手順の後半にあたります。もし切り捨てが実際に起きているなら、条件分岐の結論部分だけが欠けた指示がモデルに渡ることになります。description 1024字の上限が単なる長さの問題ではなく、「文の途中で切れる」という質の問題でもあるのは、この例が示すとおりです。
上限に近い description を書くなら、重要な条件を末尾に置かない——これが実務上の教訓になります。
上限の反対側——最短のdescriptionはどこまで短くできるか
逆方向も見ておきます。本サイトが別記事で扱った ELI5 スキルは、SKILL.md 全体が321バイト・実質3行という極小構成でした。その description はわずか144文字です。
Explain a topic like I’m a 5 year old. Use when the user types /eli5 <topic> or asks for a dead-simple picture explainer of how something works.
公式19本の最短が204字（webapp-testing / frontend-design）なので、それをさらに下回ります。そしてこの144字でも、スキルは実用上きちんと発動します。上限の1,024字は「使い切るべき予算」ではないということです。
ところが興味深いことに、この ELI5 の description を同じ公式バリデータにかけると、やはり不合格になります。
Description cannot contain angle brackets (< or >)
理由は文字数ではなく、/eli5 <topic> というプレースホルダ記法に山括弧が含まれているためです。長すぎても落ち、記号ひとつでも落ちる。裏を返せば、バリデータを通ることと実用上ちゃんと動くことは別だという証拠でもあります（ELI5 はコミュニティ配布のプラグインで、アップロード検証を経ていません）。自作スキルでプレースホルダを書きたい場合は、山括弧ではなく /eli5 [topic] のような角括弧や、単に「トピックを続けて入力」と散文で書く形に置き換えるのが安全です。
「claude-api が壊れている」という話ではありません。
quick_validate.py はアップロード型カスタムスキルの検証を模したチェッカーで、リポジトリに同梱されて配布されるスキルがこの検証を必ず通る必要があるとは限りません。実際 claude-api は現在も anthropic-agent-skills マーケットプレイス経由で問題なくインストールできます。ただし improve_description.py が言う「1024字超は切り捨てられる」が実行時にも当てはまるなら、末尾44文字分のトリガー条件が届いていない可能性は残ります。この点は公式の明示的な確認が取れていないため、断定はしません。
SKILL.mdのnameに使えない予約語——Claude Skill命名規則で公式スキルが改名された理由
文字数と並んでもう1つ、名前に関する制約があります。こちらは quick_validate.py では検査されず、実例からしか読み取れません。
2026-08-17、Anthropicは claude-academy-guide というスキルを公式スキル集に追加しました。ところが翌8-18、PR #1605 でこれが academy-guide へ改名されます。コミットメッセージが理由を明記しています。
スキル名に予約語 “claude” または “anthropic” を含めることはできない（agent skills のベストプラクティス文書に基づく）
そしてもう1点、同じコミットで description が短縮されています。
description: スキルアップロードの検証が SKILL.md frontmatter の description に課す1,024文字制限に収めるため、1,176文字から992文字へ短縮した。短縮後のテキストは内部でテスト済みの版である。
コミットメッセージの冒頭には「アップロード型のカスタムスキルとしてパッケージ可能にするための2つの変更で、それ以外の内容変更は無い」と書かれています。つまりこの改名は機能追加ではなく、配布経路の要件に合わせるためだけの調整でした。
ここから読み取れる実務ルールを整理します。
・リポジトリ同梱で配布するだけなら、名前の予約語は問題にならない（現に claude-api は予約語入りのまま存在する）
・アップロード型のカスタムスキルとして登録するなら、名前に claude / anthropic を含められない
・自作スキルを将来アップロード配布する可能性があるなら、最初から予約語を避けて命名しておくほうが安全
・改名はフォルダ名・frontmatterの name・marketplace.json のエントリ名とパスの4か所を同時に直す必要がある（PR #1605で実際にその4か所が変更されている）
配布経路によって効く制約が変わる
ここまでの話は「どの経路でスキルを配るか」で当たり方が変わります。Claude Skill 命名規則をどこまで厳密に守る必要があるかは、この経路の違いで決まります。2026-08-24時点で観測できる経路を整理すると次のとおりです。
| 配布経路 | 実体 | name の予約語 | description 1,024字 |
|---|---|---|---|
| リポジトリ同梱（マーケットプレイス） | marketplace.json を持つリポジトリを claude plugin marketplace add で追加 |
効いていない（claude-api が現存） |
検証は掛かっていない様子（同上） |
| アップロード型カスタムスキル | スキルを直接アップロードして登録 | 効く（PR #1605 の改名理由） | 効く（同PRの短縮理由） |
| ローカル配置 | 手元のディレクトリに置いて読ませる | 検証なし | 上限超過分は切り捨ての可能性 |
PR #1605 のコミットメッセージが「アップロード型のカスタムスキルとしてパッケージ可能にするため」と書いているとおり、Anthropicは同じスキルを両方の経路に乗せられるよう揃えにいきました。裏を返せば、リポジトリ同梱だけで配るなら今日は通ってしまうということでもあります。claude-api が予約語入りの名前と1,068字の description のまま存在しているのは、その証拠でしょう。
ただしこれは「守らなくてよい」という意味ではありません。後からアップロード経路に載せたくなったとき、名前を変えるとインストール識別子が変わり、既存ユーザーの設定が壊れます。PR #1605 でも4か所の同時変更が必要でした。最初から予約語を避けておくコストはゼロなので、避けておくのが合理的です。
1,176字→992字、削られたのは「精度」だった
短縮の中身を見ると、文字数制限が何を犠牲にさせるのかがはっきりします。
旧版の description は、このスキルが発動すべき対象をこう列挙していました。
artifacts、projects、skills、plugins、connectors、MCP、Claude Code、Claude Cowork、Claude in Excel、Claude in PowerPoint、Claude in Chrome、Claude API、プロンプト技法についての質問
新版ではこう縮んでいます。
artifacts、projects、skills、plugins、connectors、MCPについての質問
Claude Code・Cowork・Excel・PowerPoint・Chrome・API・prompting technique という7つの固有名が、まるごと消えました。 さらに「他のスキルが既に質問に答えていても（even when another skill has already answered the question）」という条項も削除されています。
削られたのは冗長な言い回しではなく、発動判定の手がかりそのものです。「Claude Code の使い方を教えて」という質問に対して、旧版なら description に Claude Code という文字列が直接載っていた。新版ではその手がかりが無く、より抽象的な「Claudeやその製品の使い方についての質問」という記述から判定させることになります。
Anthropic自身が「精度を犠牲にしてでも短くしろ」と書く理由
ここまで読むと「なぜそこまで厳しく制限するのか」が気になります。答えは Anthropic 自身のコードにコメントとして書かれていました。improve_description.py は、スキルの description を自動改善するためのスクリプトで、その内部プロンプトにこうあります。
リストがものすごく長くなるかもしれないし、それは全クエリに注入され、スキルは大量にあるかもしれない。だから1つのスキルに領域を使いすぎたくない。
具体的には、description は100〜200語程度を超えるべきではない。たとえそれが精度を犠牲にすることになっても。
「全クエリに注入される（injected into ALL queries）」——ここがすべてです。Agent Skillsはプログレッシブ・ディスクロージャという仕組みで動いており、毎セッション読み込まれるのは SKILL.md の本文ではなく frontmatterの description だけ。本文はスキルが実際に発動したときに初めて読まれます。
つまり description は、そのスキルを一度も使わないセッションでも払い続ける固定費です。本サイトが別記事で公式19スキルの常駐トークンを実測したところ、概ね3.3〜3.5文字あたり1トークンで推移していました。この換算を当てはめると、1,024字という上限は約300トークンの天井に相当します。実測との対応も次のとおりで、素直に線形です。
| スキル | description字数 | 実測の常駐トークン |
|---|---|---|
| claude-api | 1,068 | 約470 ※他フィールド込み |
| academy-guide | 992 | 約320 |
| discernment-nudge | 983 | 約320 |
| xlsx | 948 | 約330 |
| doc-coauthoring | 428 | 約150 |
| skill-creator | 319 | 約110 |
| webapp-testing | 204 | 約80 |
注目したいのは skill-creator です。本文は33,168バイトと19本中で最大なのに、description は319字しかなく常駐は約110トークン。逆に discernment-nudge は本文10,592バイト（約3分の1）ながら常駐は約320トークンで、3倍近い。常駐コストは本文の長さと無関係で、description の長さだけで決まることがここでも確認できます。スキルの実測の詳細は discernment-nudgeとは｜AIの答えを疑わせるAnthropic公式スキルを実測、常駐317トークンの中身 にまとめました。
descriptionの書き方として推奨されていること
同じプロンプトには、書き方の指針も列挙されています。文字数を削りながら発動精度を保つための実務的なヒントとして使えます。
・命令形で書く——「このスキルは〜をする」ではなく「〜のときにこのスキルを使え」
・ユーザーの意図に寄せる——実装の詳細ではなく、ユーザーが達成しようとしていることを書く
・他スキルとの区別を明確に——description は他のスキルとClaudeの注意を奪い合っているので、識別しやすく特徴的にする
・失敗例に過適合しない——発動しなかったクエリを個別に列挙し続けるのではなく、より広い意図のカテゴリへ一般化する
4つ目が実質的に一番効きます。academy-guide の短縮がまさにこれで、7つの製品名という個別列挙を捨て、より上位の概念で括り直した形になっています。
64字以内か？"} B -- いいえ --> X["不合格
名前を修正"] B -- はい --> C{"description に
山括弧を含まないか？"} C -- 含む --> X C -- 含まない --> D{"description は
1,024字以内か？"} D -- 超過 --> Y["不合格
または黙って切り捨て"] D -- 以内 --> E{"アップロード配布
する予定か？"} E -- はい --> F{"name に claude /
anthropic を含まないか？"} F -- 含む --> X F -- 含まない --> G["検証通過"] E -- いいえ --> G
自作スキルのチェックリスト——起票前に走らせる
最後に、自作スキルを配布する前の実務手順としてまとめます。仕様書を読み返すより、公式バリデータを直接走らせるほうが速くて確実です。
# 公式バリデータを取得（skill-creator に同梱されている）
git clone --depth 1 https://github.com/anthropics/skills.git /tmp/anthropic-skills
# 自作スキルのディレクトリを検査する
python3 /tmp/anthropic-skills/skills/skill-creator/scripts/quick_validate.py ./my-skill
Skill is valid! が返れば形式面は通っています。加えて、コードでは検査されないが実務上効く項目を手動で確認します。
| 確認項目 | 判定方法 | 効いてくる場面 |
|---|---|---|
| description が1,024字以内か | バリデータが自動判定 | アップロード検証・切り捨て回避 |
| name が64字以内・kebab-case か | バリデータが自動判定 | 同上 |
name に claude / anthropic を含まないか |
手動確認（バリデータは見ない） | アップロード型で配布するとき |
| description が100〜200語程度に収まっているか | 手動確認 | 常駐トークンの節約 |
| 常駐コストが許容範囲か | claude plugin details <name> で実測 |
複数スキルを常用するとき |
| トリガー語が個別列挙になっていないか | 手動確認 | 上限に当たったときの削りしろ |
プラグインとして配布する形にしたなら、
claude plugin details <プラグイン名> で「Always-on」（毎セッション加算）と「on-invoke」（発動1回あたり）が表示されます。descriptionを削る前後で実行すれば、削減効果をトークン単位で確認できます。ただしこの値はCLIが出す見積もりで、CLIのバージョンが変わると同じスキルでも数字が変わります（本サイトでは 2.1.220 → 2.1.241 でELI5の常駐が約39→約66に変化することを確認済み）。バージョンをまたいだ絶対値の比較には使えません。
つまずきやすい4点
実際に検査を回すと引っかかりやすいのは、上限そのものより周辺の仕様です。
・YAMLのブロックスカラーで書いた description の字数を見誤る——公式スキルの多くは description: > の折り畳み記法を使っています。この記法は改行を半角スペース1つに畳むため、ソース上の見た目の文字数とパース後の文字数が一致しません。字数を数えるときは生のテキストではなく、YAMLとしてパースした後の文字列長を測ってください。本記事の数値もすべてパース後の値です
・山括弧を書いてしまう——<topic> のようなプレースホルダを description に入れると Description cannot contain angle brackets で弾かれます。本文（frontmatterの外）なら問題ありません
・大文字やアンダースコアを含む name——My_Skill や mySkill は kebab-case 違反です。ディレクトリ名とfrontmatterの name は揃えておくのが無難です
・description を伸ばして発動精度を上げようとする——上限が近いスキルでは逆効果になります。伸ばすのではなく、improve_description.py が言うとおりより広い意図のカテゴリへ一般化する方向で書き換えます
なお quick_validate.py が検査するのは frontmatter の形式面だけで、本文の内容や発動精度は一切見ません。「valid」が返っても、それは配布要件を満たしたという意味であって、狙いどおり発動するかは別問題です。発動の確認は実際にプロンプトを投げて、スキル有無で出力が変わるかを見るしかありません。
スキルそのものの構造や作り方は Claude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説 にまとめてあります。本記事はその中でも「配布・検証で実際に弾かれる条件」に絞った内容です。
まとめ
・description は1,024字が上限。超過分は切り捨てられる経路があり、エラーで止まるとは限らない
・name は64字以内・kebab-case のみ。先頭末尾のハイフンと連続ハイフンも不可
・アップロード型では name に
claude / anthropic を使えない。実際に公式スキルが1日で改名された・公式19本中1本（claude-api・1,068字）が公式バリデータで不合格。上限運用は公式でもぎりぎり
・Anthropicは「精度を犠牲にしてでも短くしろ」と明記。理由は description が全クエリに常駐するから
・1,024字は常駐約300トークンの天井に相当。本文をいくら厚くしても常駐は増えない
上限に当たったときの削り順
最後に、description が1,024字を超えてしまったときの実務的な削り順をまとめます。academy-guide の短縮（1,176→992字）で実際に行われた順序をなぞったものです。
- 個別列挙をカテゴリへ畳む——製品名や機能名を並べている箇所が最初の削りしろ。7つの固有名を「Claudeとその製品」に畳めば100字単位で減る
- 条件の但し書きを落とす——「他のスキルが既に答えていても」のような二次的な条項は、効果に対して字数を食う
- 重複する言い換えを1つにする——同じ意図を2通りで書いている箇所を統合する
- それでも足りなければトリガー語を削る——ここまで来ると発動精度に直接効くので、どのトリガーを捨てるかは実際の利用シーンで判断する
逆にやってはいけないのは、本文（frontmatterの外）を削ることです。本文は発動時にしか読まれないため、削っても常駐コストは1トークンも減りません。減るのは発動したときの情報量だけで、まったくの逆効果になります。
この制約群が面白いのは、すべてが同じ1つの事実から出ていることです——description は全クエリに注入される。だから短くしろと言われ、だから1,024字の壁があり、だから公式スキルですら製品名リストを泣く泣く削る。スキルを増やすほど、この固定費は積み上がります。
自作スキルを書くときの優先順位も、そこから決まります。本文は好きなだけ厚く書いてよい。削るべきは description のほうだけで、しかも削り方は「言い回しを縮める」ではなく「個別列挙をより広い意図に一般化する」——Anthropic自身が公式スキルの改名でやってみせたとおりです。
参照ソース
・anthropics/skills — skill-creator/scripts/quick_validate.py — name 64字・description 1,024字・山括弧禁止・compatibility 500字という検査ルールの実装元
・anthropics/skills — skill-creator/scripts/improve_description.py — 「全クエリに注入される」「精度を犠牲にしても100〜200語」「超過分は truncated」の記述元
・anthropics/skills PR #1605 — Rename claude-academy-guide skill to academy-guide and shorten its description — 予約語ルールと1,176→992字短縮の一次記録（2026-08-18 09:02:05 PDT、コミット 0a64e39）
・Agent Skills Specification — 仕様書の現在地（リポジトリ内 spec/ からの移管先）
