スキルの名前は動名詞形で揃え、description は短い英語で「何を・いつ」
公式のベストプラクティスは、スキル名を processing-pdfs のような動名詞形（verb+ing）で揃えることを勧めている。全スキルの name と description は起動時に毎回読み込まれるので、増えてきたら description を英語にして削る。
なぜ大事？
- 起動時に読み込まれるのは全スキルの
nameとdescriptionだけ。スキルが多いと、この部分だけでコンテキストを圧迫する（@mizchi は英語に書き直してチューニング） - Claude は100件以上のスキルから description を見て選ぶ。曖昧だと発火しない、または誤発火する
ルール（Claude の Agent Skills ベストプラクティスより）
name: 64文字以内、英小文字・数字・ハイフンのみ。anthropicとclaudeは使えない- 名前の型を揃える: 推奨は動名詞形（
processing-pdfs、analyzing-spreadsheets、writing-documentation）。名詞句（pdf-processing）や動詞形（process-pdfs）も可。helper・utils・toolsのような曖昧な名前は避ける description: 1,024文字以内。三人称で、「何をするか」と「いつ使うか（きっかけになる語）」の両方を書く
yaml
name: processing-pdfs
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.手順
- 手元のスキル一覧を出し、名前の型がばらばらなら揃える
- description を「三人称の1〜2文＋Use when …」に書き直す。長い説明は SKILL.md 本文に移す
- 書き直したら、いつもの依頼で発火するか実際に確かめる
注意点
- 名前を変えると、スキルを呼んでいる他のスキルやルーチンの参照が切れる。変える前に grep する
- 日本語の description でも動くが、トークン数は英語のほうが少なくなりやすい
- 関連: AIコーディング: skills を入れすぎない → 「skill-selector」だけ常駐させ、リポジトリごとに明示的に入れる、スキルは「再現性テスト×モデル別の採点」で育てる。詰め込みすぎたら分割する