Anthropicが公開したSKILL.md Body記述ルール5つ

SkillはYAMLフロントマター2行で作れます。しかしbodyの書き方ひとつで、出力品質がまったく変わります。

Anthropic公式ドキュメントとエンジニアリングブログを照合しながら、動作構造とbody記述の原則を整理しました。自作Skillが時々読み込みに失敗するため、連休を使って一から検証した結果です。

Skillの実行順序を知らないとbody設計が破綻する

Skillはプロンプトのように会話に直接注入されません。起動時にシステムプロンプトに載るのはnameとdescriptionだけです。

ユーザーのリクエストがdescriptionと合致したとき、ClaudeがBashツールでSKILL.mdの全文を読み込み、その後で参照ファイルやスクリプトを必要なタイミングで追加ロードします。Anthropicのエンジニアリングブログでは、この構造を「段階的開示（progressive disclosure）」と呼んでいます。

• 第1段階: メタデータ（name + description）のみ常時ロード。Skill1つあたり約100トークン
• 第2段階: SKILL.md bodyはマッチング時のみコンテキスト範囲に入る
• 第3段階: scriptsフォルダ・referencesフォルダのファイルは実際の参照時にロード
• スクリプト実行時、コード自体はコンテキストに載らず出力値のみ消費

この構造を理解していないと、bodyに不要な情報を詰め込み、本当に必要な情報を落とすことになります。

bodyに「いつ使うか」を書くとトークンの無駄になる

多くの人がbodyに「When to Use This Skill」セクションを入れています。実際に作ってみると、これはまったく意味がありませんでした。bodyはSkillが発動した後に読まれるからです。

「いつ使うか」はdescriptionにだけ書くべきです。Anthropic公式のskill-creatorリポジトリでもこの点を明記しています。

• descriptionが唯一のトリガー（bodyに書いてもClaudeは参照しない）
• descriptionは最大1,024文字。三人称で書くと検出精度が上がる
• bodyに入れるべきは作業ルール、手順、期待される出力形式
• 「このSkillは〜のときに使います」のような文はbodyから削除

bodyは500行以内に収め、残りは分離する

コンテキストウィンドウは共有資源である, , これがAnthropicガイドの冒頭の一文です。Skillがロードされると、会話履歴やシステムプロンプトとトークンを分け合うことになります。

bodyを500行以下に保ち、詳細は別ファイルに切り出すのが公式推奨です。SKILL.mdが目次の役割を果たし、参照ファイルが各章になる構造です。

• body 500行以下を推奨（Anthropicベストプラクティスに明記）
• 参照ファイルはSKILL.mdから1階層の深さでのみリンク
• 2階層以上のネスト参照ではClaudeがhead -100で一部しか読まないリスク
• 100行超の参照ファイルには冒頭に目次を入れること

Claudeはすでに賢いという前提で書く

bodyにPDFとは何かを説明するのはトークンの無駄です。Anthropicガイドが繰り返し強調している原則があります。

「Claudeがすでに知っていることは書くな。」

50トークンの簡潔なコード例が、150トークンの概念説明よりも高い性能を発揮します。同じPDF抽出タスクで比較したところ、簡潔なbodyの方が明らかに精度が高い結果が出ました。

• すべての文に「この説明はトークンに見合う価値があるか？」と自問する
• 概念説明の代わりにコード例 + 期待出力形式で記述
• タスクの自由度を3段階（高/中/低）に分けて指示の強度を調節
• DBマイグレーションのようなタスクは自由度を低く、コードレビューは高く設定

検証ループをbodyに埋め込むと品質が上がる

実行 → 検証 → 修正 → 再検証。Anthropicが提示するbodyパターンの中で最も実用的な部分です。チェックリストをbodyに入れると、Claudeがステップを飛ばす確率が目に見えて下がります。

「MUST filter」のような強い表現が「always filter」よりも遵守率が高いという点も公式ガイドに記載されています。

• 複雑なタスクにはチェックリスト形式でステップを明示
• スクリプト検証 → エラー修正 → 再検証のループをbodyに含める
• 「always」の代わりに「MUST」を使うとClaudeの遵守率が上がる
• エラーメッセージは具体的に書くとClaudeが自動修正できる

まとめ

descriptionは「いつ使うか」を決め、bodyは「どう実行するか」を決めます。この2つの役割を混ぜた瞬間、Skillは発動もしなくなり品質も落ちます。

優れたSkillは優れたオンボーディングドキュメントと同じです。読む人が賢いという前提から始まるドキュメントが、最も強力です。