Claude Code Skillが自動発動しない——description文字数を全14スキルで実測した検証ログ

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字）に近いかを確認

プロジェクトSkillsはfrontmatterのdescription:を直接参照した。

読者のよくある詰まり

• Skillを作ったが「使ってみた系の処理をして」と言っても呼ばれない
• GitHubやQiitaで「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
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/）

スキル名	description文字数
aidesigner-frontend	312字
article-policy	135字
publish-gate	124字
entry-triage	104字

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

原因分析：1536字制限の正確な意味

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に書かれていないこと**だ。

自分が最初に作ったSkillの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の設定を見直す。

今日やること

1. 自分の全SkillのdescriptionをリストアップしてClaude Codeに計測させる（cat manifest.json | python3）
2. 各descriptionに「いつ呼ぶか（when to use）」が含まれているかをチェック
3. トリガー条件が曖昧なSkillを1本だけ書き直してテストする

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