Anthropic公式ガイドが示す、Claude Skillを実際に機能させる条件

Skillとは、Claudeがタスクの途中で開けるフォルダだ。SKILL.mdファイルに加え、必要に応じてスクリプトや参考資料を収める。利点は、Claudeが実際に使うものにしかコストを割かないことにある。Skillの大部分は、会話の内容から必要になるまでコンテキストウィンドウの外に置かれる。Anthropic公式の作成ガイドは、Skillに何を入れるべきかよりも、何を省くべきかに多くの紙幅を割いている。その助言の枠組みは、そのまま取り入れる価値がある。

descriptionフィールドがすべてを決める

ClaudeがSkillを開く前に目にするのは、YAMLフロントマター内のdescriptionフィールドだけで、上限は1,024文字だ。Anthropicの指針は具体的で、三人称で書き（「Excelファイルを処理する…」とし、「Excelファイルの処理をお手伝いできます…」とはしない）、そのSkillが何をするのか、いつ使うのかの両方を明記するよう求めている。同時に100を超えるSkillが利用可能になる場合、この一文は候補を照合するための手掛かりとなる。Claudeはdescriptionだけを基に候補から選ぶため、内容が曖昧だとSkillはひっそりと選択肢から外れ、理由を示すエラーも出ない。

nameフィールドはより短いが、独自の規則がある。最大64文字で、小文字、数字、ハイフンのみを使用でき、「claude」や「anthropic」を含めてはならない。Anthropicは、曖昧な名前（helper、utils）ではなく、動名詞形式の名前（processing-pdfs、analyzing-spreadsheets）を推奨している。

3段階、3種類のコスト

Skillは段階的に読み込まれる。このコスト構造こそ、現在の形式が採用されている理由だ。

この構造は、サイズ制限が設けられている理由でもある。Anthropicは、SKILL.mdの本文を5,000トークン未満かつ500行未満に抑えることを推奨している。それを超える内容は別ファイルに移してリンクすればよい。Claudeが開くまでコストは発生しない。

参照ファイルは1階層までにする

Claudeが一部しか読まないファイルは、まったく読まないファイルより厄介だ。Anthropicの指針は、Claudeが深くネストされた参照の連鎖を全文ではなく流し読みする可能性があると警告している。実質的にはhead -100のような処理になるため、SKILL.mdから2リンク以上離れた情報は、不完全に読まれる恐れがある。100行を超える参照ファイルには、冒頭に目次を置くべきだ。そうすれば、一部しか読み込まれなくても、Claudeは利用できる情報の全体像を把握できる。

起こり得る失敗に合わせて指示を設計する

すべてのSkillに同じ種類の指示が必要なわけではない。Anthropicはこれを「自由度」という考え方で説明している。文書の要約やメールの下書きなど、判断が大きく関わるタスクは、柔軟で自由度の高い表現で記述できる。一方、データベース移行や特定のAPI呼び出し手順など、壊れやすい処理や一貫性が必須の処理は、厳密で自由度の低いスクリプトによって固定すべきだ。壊れやすい処理を曖昧な文章で指示すると、Skillは気付かれないまま失敗しやすい。

長大な説明を書く前に、基準となる挙動をテストする

推奨される手順は省略しやすいが、省けば後悔しやすい。詳しいドキュメントを書く前に、Claudeで少なくとも3つの実際のテストシナリオを実行し、Skillがない状態でClaudeが何を誤るのかを確認する。そうしなければ、Claudeが実際には抱えていない問題の解決に何段落も費やしかねない。Anthropicはまた、完成したSkillを、使用予定のすべてのモデルでテストするよう推奨している。Haiku、Sonnet、Opusの挙動は同一ではなく、Opusには十分簡潔な指示でも、Haikuには情報不足となる場合がある。

ソフトウェアのインストールと同様に扱う

Anthropicは明確に述べている。使用するのは、自作したSkillか、Anthropicから直接提供されたSkillだけにすべきだ。SkillはClaudeにツールの不正使用やデータの持ち出しを指示でき、信頼できないSkillを標準で安全にするサンドボックス機構は存在しない。自分で書いていないMarkdownやスクリプトのフォルダも、エージェントに実行させようとしているコードに変わりはない。

日付を確認すること。 Anthropic公式のベストプラクティス文書は、「2025年8月以前はXを使う」といった時期に左右される表現を埋め込まないよう警告している。Skillの内容は自動更新されず、同じ注意はこの記事にも当てはまる。上記の各環境における提供状況がその後変わっている可能性があるため、リンク先のドキュメントを直接確認してほしい。