Skillを作ったのに呼ばれない。そんな経験をした時、よく「descriptionが長すぎるから」という解説に行き着く。

「1536字でカットされる」という数値がいくつかの記事で言及されていて、これを見た人が「自分のdescriptionを短くしなければ」と思い込むケースがある。実際に手元の全Skillのdescription文字数を数えて検証した。

結論：文字数は犯人ではなかった

実測した14スキルは全て1536字未満（最長948字）で、現在全て正常に自動発動している。

1536字という数値は本物の制限だが、「それを超えているからSkillが呼ばれない」という状況は実運用でほぼ起きない。実際には**「いつ呼ぶか」がdescriptionに書かれていないこと**が発動しない原因の大半を占める。

この記事の前提

検証環境:

何を測ったか:

ユーザーSkills（~/.claude/skills/）

スキル名	description文字数	when_to_use	合計	1536字超
xlsx	948字	0字	948字	✅ OK
docx	835字	0字	835字	✅ OK
pptx	732字	0字	732字	✅ OK
pdf	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/）

全18スキル、1536字超えはゼロ。when_to_useフィールドを使っているSkillも現時点では存在しない。

Claude Code公式ドキュメントには次の記述がある：

"the combined description and when_to_use text 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）と「いつ使うか」の具体例が詰め込まれているからだ。文字数が多いのではなく、トリガー条件が明確だから呼ばれる。

1. 「いつ呼ぶか」が入っているか

2. 動詞と対象が具体的か

❌ Code reviewer
✅ Performs code review when the user asks to review a PR or check code quality

3. トリガーフレーズが自然言語に近いか

文字数を削る前に、この3点を確認する。これで解決しない場合はdisable-model-invocationやuser-invocableの設定を見直す。

文字数制限は存在するが、通常の運用で問題になる前に、description設計の方を直した方が発動率は上がる。

AI ツールを業務に組み込む設計の実験ログを書いています。 https://masatoman.net