Skillを作ったのに呼ばれない。そんな経験をした時、よく「descriptionが長すぎるから」という解説に行き着く。
「1536字でカットされる」という数値がいくつかの記事で言及されていて、これを見た人が「自分のdescriptionを短くしなければ」と思い込むケースがある。実際に手元の全Skillのdescription文字数を数えて検証した。
結論：文字数は犯人ではなかった
実測した14スキルは全て1536字未満（最長948字）で、現在全て正常に自動発動している。
1536字という数値は本物の制限だが、「それを超えているからSkillが呼ばれない」という状況は実運用でほぼ起きない。実際には**「いつ呼ぶか」がdescriptionに書かれていないこと**が発動しない原因の大半を占める。
この記事の前提
検証環境:
- Claude Code（claude.ai/code）
- ユーザーレベルSkills（
~/.claude/skills/）：14スキル - プロジェクトレベルSkills（
.claude/skills/）：4スキル - 計測：2026年8月時点
何を測ったか:
- 各Skillの
manifest.jsonからdescriptionフィールドの文字数を取得 -
when_to_useフィールドの有無を確認 - 両者の合算が公式上限（1536字）に近いかを確認
よくある詰まり
- Skillを作ったが期待した文脈で呼ばれない
- 「descriptionが長いと呼ばれない」という情報を見てdescription削減を試みた
- 削減しても改善しなかった
実測データ：14スキルの文字数テーブル
ユーザーSkills（~/.claude/skills/）
| スキル名 | description文字数 | when_to_use | 合計 | 1536字超 |
|---|---|---|---|---|
| xlsx | 948字 | 0字 | 948字 | ✅ OK |
| docx | 835字 | 0字 | 835字 | ✅ OK |
| pptx | 732字 | 0字 | 732字 | ✅ OK |
| 437字 | 0字 | 437字 | ✅ OK | |
| doc-coauthoring | 428字 | 0字 | 428字 | ✅ OK |
| morning | 339字 | 0字 | 339字 | ✅ OK |
| internal-comms | 329字 | 0字 | 329字 | ✅ OK |
| skill-creator | 319字 | 0字 | 319字 | ✅ OK |
| algorithmic-art | 324字 | 0字 | 324字 | ✅ OK |
| canvas-design | 289字 | 0字 | 289字 | ✅ OK |
| web-artifacts-builder | 288字 | 0字 | 288字 | ✅ OK |
| mcp-builder | 277字 | 0字 | 277字 | ✅ OK |
| theme-factory | 262字 | 0字 | 262字 | ✅ OK |
| brand-guidelines | 236字 | 0字 | 236字 | ✅ OK |
プロジェクトSkills（.claude/skills/）
| スキル名 | description文字数 |
|---|---|
| aidesigner-frontend | 312字 |
| article-policy | 135字 |
| publish-gate | 124字 |
| entry-triage | 104字 |
全18スキル、1536字超えはゼロ。when_to_useフィールドを使っているSkillも現時点では存在しない。
1536字制限の正確な意味
Claude Code公式ドキュメントには次の記述がある：
"the combined
descriptionandwhen_to_usetext is truncated at 1,536 characters in the skill listing to reduce context usage."
これは「descriptionだけで1536字」ではなく、descriptionとwhen_to_useの合算が1536字でカットされるという仕様だ。
例えばdescriptionが900字で、when_to_useが700字なら合計1600字となり、末尾の60字が落ちる。しかし自分のSkillの最長は948字（xlsx）でwhen_to_useはゼロ。1536字制限はまだ相当余裕がある。
では本当に呼ばれない原因は何か
主因は**「いつ呼ぶか」がdescriptionに書かれていないこと**だ。
例えばdescriptionが「マイグレーションをチェックする」という12文字しかなければ、Claudeは「いつ呼べばいいか」がわからない。「新しいSupabaseマイグレーションを作って」というリクエストが来ても、このdescriptionと照合するトリガーがない。
xlsx（948字）の長いdescriptionが機能する理由は、ファイルタイプの列挙（.xlsx, .xlsm, .xltx, .csv, .tsv）と「いつ使うか」の具体例が詰め込まれているからだ。文字数が多いのではなく、トリガー条件が明確だから呼ばれる。
発動しない時に先に確認すべき3点
1. 「いつ呼ぶか」が入っているか
- ❌
Skillの目的を一行で説明する文 - ✅
ユーザーが〇〇と言った時、または〇〇ファイルを扱う時に呼ぶ
2. 動詞と対象が具体的か
- ❌
Code reviewer - ✅
Performs code review when the user asks to review a PR or check code quality
3. トリガーフレーズが自然言語に近いか
- ユーザーが実際に使う言葉（"commit", "deploy", "review PR"）がdescriptionに含まれているかを確認する
- Claudeはユーザーの入力とdescriptionをマッチングしているので、ユーザーが言わない言葉を書いても機能しない
文字数を削る前に、この3点を確認する。これで解決しない場合はdisable-model-invocationやuser-invocableの設定を見直す。
まとめ
- 自分の全Skillのdescription文字数を計測する（
cat ~/.claude/skills/manifest.json | python3） - 各descriptionに「いつ呼ぶか（when to use）」が含まれているかをチェック
- トリガー条件が曖昧なSkillを1本だけ書き直してテストする
文字数制限は存在するが、通常の運用で問題になる前に、description設計の方を直した方が発動率は上がる。
AI ツールを業務に組み込む設計の実験ログを書いています。 https://masatoman.net