Anthropicのドキュメントは明確です：SKILL.mdは500行未満にすべきです。しかし、公式のdocxスキルは590行です。マーケットプレイス構築中に、Anthropicの17公式スキルをすべてfrontmatterごとに読みました。毎回同じギャップ：ドキュメントは一つのことを言い、コーパスは別のことをする。そして正しいのはコーパスです。

ここで、ドキュメントではなくコードを読んだときに実際にわかったことを紹介します。

descriptionがスキルの90%を占める

スキルは適切なタイミングでトリガーされなければ役に立ちません。トリガーを決めるのはSKILL.mdの本体ではなく、frontmatterのdescriptionです。Claudeは利用可能なスキルのリスト（名前＋descriptionのみ）を読み、選択します。そのため「いつ使うか」のすべては本体ではなくdescriptionに含める必要があります。

直感に反する部分ですが、Anthropic自身のskill-creatorでも繰り返し述べられています：Claudeはスキルをオーバートリガーするよりアンダートリガーする方がはるかに多いです。Claudeは自力で処理できないタスクに対してのみスキルを参照します。「このPDFを読んで」は、完璧なdescriptionであってもPDFスキルを発火させることはありません。そのため、明示的な指示として、descriptionは少し押しが強い書き方にする必要があります。

コードを見ると：xlsxスキルは「スプレッドシートファイルが主な入力または出力であるあらゆる場合にこのスキルを使用」とあり、pptxは「.pptxが何らかの形で関与するあらゆる場合」とあります。控えめではなく、積極的にトリガーを促す書き方になっています。

誰も守らない500行ルール

「SKILL.mdは500行未満に保つ」は最も引用されるルールのひとつです。実際にはdocxは590行で、ドキュメント自体にも「必要に応じて長くても構わない」とあります。他のスキルは32行から404行の範囲です。真実は、500行は目標であって法律ではないということです。

その背後にある本当の原則は長さではなく、コンテキスト予算です。SKILL.md本体はトリガーされるたびに読み込まれます。本質的な内容を含むために大きいのであれば、500行を超えても問題ありません。別ファイルに置ける詳細を引きずっているために大きいのであれば、それが問題です。サイズ自体が罪ではありません。

プログレッシブディスクロージャー：主にscripts、referencesは稀

スキルの中心的なパターンは段階的な読み込みです：メタデータ（名前＋description）は常にコンテキストにあり、本体はトリガー時に読み込まれ、リソース（scripts/、references/）は要求されたときのみ読み込まれます。スクリプトはコンテキストに読み込まれなくても実行可能です。

ただしコーパスでは、17スキルのうち11スキルが単一のSKILL.mdで、サブフォルダが一切ありません。分割は標準ではなく、ドメインがそれを必要とするときに到達する例外です。分割する場合も主にscripts/です：pdf、docx、xlsx、pptxは、まず決定論的な操作のためのスクリプトボックスです。references/（オンデマンドで読み込まれるドキュメント）は2つのスキルにしか存在しません。教訓：散文を別ファイルに引き出す前に、決定論的な処理を実行可能なコードに引き出すべきです。

Anthropicが書かない「NOT for」

自分でスキルを書く際、誤ったトリガーを避けるためにdescriptionに「NOT for X」という句を体系的に追加していました。公式のスキルを読み、驚いたことに：それらはほとんど書いていません。descriptionは除外ではなく包含（「これには…が含まれる」）を列挙しています。

理由は一言で言えます：それらのドメインは重複しないからです。PDFスキルとExcelスキルが混同されることはないため、除外は必要なく、むしろトリガーを最大化したいのです。私の場合は異なります：私のスキルは互いに触れ合っています（diffのレビュー、機能のリリース、ブランチのラップアップなどは隣接しています）。「NOT for」は自分のスキル同士を区別するためのものです。つまり普遍的なルールではなく、重複に対する対応策です。スキル同士が競合しない場合は追加しない方が良く、追加すればトリガーを減らすことになり、これが最も避けるべき欠陥です。

descriptionを実際に最適化する方法

公式のskill-creatorで最も参考になるのは、良いdescriptionを推測するのではなく、測定している点です。プロトコルは以下の通りです：

  • 20の評価クエリ：トリガーすべきクエリ8〜10件、トリガーすべきでないクエリ8〜10件。実際のユーザーが入力するような現実的で乱雑なもの（ファイルパス、個人的な文脈、タイポ、小文字）。
  • ネガティブはニアミス、明らかなものではありません。「フィボナッチ関数を書いて」はPDFスキルのネガティブとしては何もテストしません。良いネガティブはスキルとキーワードを共有しつつ、別のものを必要とするものです。
  • 各クエリを3回実行して信頼できるトリガー率を測定し、5回の反復で改善ループを回します。
  • descriptionはホールドアウトテストセットでのスコアで選ぶ（学習60%、テスト40%）ため、すでに知っているクエリに過学習しません。

これは勘ではなく評価パイプラインです。ほとんどの人は感じでdescriptionを書いて終わりにします。Anthropicはそれをプロダクトとして扱っています。

一目でわかる：前提と実際

17の公式スキル全体にわたる前提と実際のギャップを行ごとに示します：

一般的な前提

公式コーパスが実際に行っていること

SKILL.mdは500行未満である

docxは590行で、ドキュメントには「必要に応じて長くしてもよい」とある

descriptionはスキルの使い時を述べるだけである

それは押しが強いものでなければならない：本当のリスクはアンダートリガーである

references/とscripts/に分割する（プログレッシブディスクロージャー）

17スキルのうち11スキルが単一ファイル。分割する場合も主にscripts/

誤ったトリガーを避けるためにdescriptionを制限する（「NOT for」）

ほとんど書かれていない：ドメインが明確に分かれているため、トリガーを最大化する

良いdescriptionは勘で書く

測定されている：20クエリ、各3回実行、5回の反復ループ、ホールドアウトテストセットでスコアリング

覚えておくべきこと

本当の教訓はルールのリストではなく、そのギャップにあります。ドキュメントはきれいなヒューリスティックを提供しますが、コーパスは、現場が要求するときに有能な人々がどのようにそれを曲げているかを示しています。17のスキルを読み込むことは、ドキュメントページを読むことよりも多くのことを教えてくれます。なぜなら、本当に必要なときに500行を超えたり、3分の2の時間で分割をスキップしたり、トリガーを制限するのではなく積極的に促したりする、実際のトレードオフが見えるからです。

一つだけ覚えておくなら：スキルのリスクはトリガーしすぎることではなく、トリガーされないことです。descriptionは見つけられるように書きましょう。

🧩 私のスキル、インストール可能

私は実際のワークフローからClaude Codeスキルのマーケットプレイスを構築し、これらのパターンを適用しました。Skillsページで閲覧・インストールできます。原則を凝縮したskill-builderスキルも含まれています。エージェントをフレーム化するには、CLAUDE.md contextsもご覧ください。

よくある質問

SKILL.mdは何行にすべきですか？

500行未満を目指してください。ただし法律ではありません：公式のdocxスキルは590行です。重要なのは、本体がスクリプトやリファレンスファイルに置くべき詳細を引きずらないことです。本質的な内容が正当化するなら超えても構わず、その後でサイドファイルへのポインタを追加してください。

スキルがトリガーされないのはなぜですか？

ほぼ常にdescriptionの問題です。Claudeはデフォルトでアンダートリガーし、非自明なタスクに対してのみスキルを参照します。descriptionをより包括的で「押しが強い」ものにしましょう（「このスキルは…のときいつでも使用…ユーザーが明示的に言わなくても…」）。実際のトリガーフレーズを入れ、テストしてください。ワンステップのタスクは決してスキルをトリガーしません。これは正常です。

references/とscripts/フォルダは必要ですか？

デフォルトでは必要ありません：17の公式スキルのうち11スキルが単一のSKILL.mdです。ドメインが重いときに分割し、その場合も主に決定論的な作業（ファイル操作、検証）のためにscripts/に分割します。references/が意味を持つのは、大規模で多様なバリアントを持つドメインの場合だけです。

Skill、CLAUDE.md、hookの違いは？

Skill = 状況がそれを必要とするときにdescriptionによってトリガーされる機能。CLAUDE.md = 特定のプロジェクトに対して常に読み込まれるコンテキスト。Hook = イベント発生時にハーネスによって強制される決定論的な自動化（モデルによるものではない）。「常にXを実行する」場合は、スキルではなくhookまたはCLAUDE.mdです。