私のSkillの内容が本当に複雑な場合、無理に500行以内に収めると説明の完全性を犠牲にすることになりませんか？
この懸念の背後には誤解がある：500行の制限は本体に適用されるのであって、Skillが伝えられる情報の総量ではない。完全性を犠牲にする必要はなく、再分配すればよいだけだ——Claudeがトリガーされるたびに必ず必要となるコアロジックは本体に残し、特定の状況でのみ必要な詳細は拡張ファイルに移す。
実務上、複雑なSkillは通常、複数の使用状況をカバーしていることを示している。この場合、より問うべきなのは：これらの状況の記述が曖昧すぎて、実はそれぞれ専門化され個別にトリガーされる複数のSkillに分割できるのではないか、ということだ。一つのSkillが一つのことだけを行う方が、すべての状況をカバーしようとする巨大なSkillよりも、通常はトリガー精度が高く、保守も容易である。
複数ファイルからなるSkillの場合、フォルダ構造はどう整理すべきですか？
一般的な慣例は、Skillごとに独立したフォルダを用意し、メインエントリーとしてSKILL.mdを置き、scripts/（実行可能なコード、通常は小型のCLIツールとして設計）、references/（スキーマやチートシートなど補足的な背景資料）、assets/（テンプレートや出力時に使う静的ファイル）といったサブディレクトリを内容の性質に応じて分類する方法だ。
この構造の背後にあるロジックは3層開示メカニズムと一致している：Skill.mdはナビゲーションと高レベルのプロセス説明を担当し、各サブディレクトリには「必要なときにだけ読む」または「必要なときにだけ実行する」内容が置かれる。リンクの深さは1階層に留めることが推奨される——SKILL.mdがreferences/配下のファイルに直接リンクし、references/内のファイルがさらに深い階層のファイルにリンクすることは避けるべきだ。そうしないと、Claudeが一つの詳細を調べるために何度も連続してジャンプすることになり、段階的開示が本来節約しようとしていたコストに反してしまう。
description フィールドは機能を明確に書く以外に、実務上見落とされがちなポイントはありますか？
最も見落とされがちなのは、descriptionには「このSkillが何をするか」と「どんな状況で使うべきか」の両方を含めるべきで、単なる機能説明だけではいけないという点だ。例えば「Gitのcommitメッセージを処理する」とだけ書くのは曖昧で、「ステージ済みの変更に対してcommitメッセージを書くときに使用する」と書けば機能とトリガー状況の両方をカバーでき、Claudeがユーザーのリクエストと照合する際により正確に判断できる。
もう一つ見落とされがちなポイントは具体的なキーワードだ。ユーザーが実際にタイプするとき、開発文書のような正式な用語を使うことは少なく、むしろ口語的な言い回しを使うことが多い。descriptionにユーザーが実際に口にしそうな単語や状況説明を含められれば、専門用語を積み重ねただけの説明よりもトリガー精度が明らかに向上する。これが、一つのSkillが一つのことだけを行う方がトリガーされやすい理由でもある——機能が単一だからこそ、descriptionを十分に具体的に書けるのだ。
すでに500行を超えるSKILL.mdをいくつか使用していますが、すぐに書き直す必要がありますか？
慌ててすべてを一度に書き直す必要はないが、優先順位をつけて見直す価値はある。優先的に処理すべきかどうかの判断シグナルは、そのSkillのトリガー頻度と、トリガー時に他のタスクと同時進行することが多いかどうかだ。超長文のSkillがトリガー頻度も高い場合、そのたびに他のコンテキスト内容を薄めていることになり、優先度は最も高くすべきだ。逆にめったにトリガーされないSkillであれば、500行を大幅に超えていても緊急性は相対的に低い。
書き直しの際に推奨される順序は：まずdescriptionを見直し、トリガー判断そのものに問題がないか確認する。次に本体の内容を「コアロジック」と「状況的な詳細」に分類し、状況的な詳細を暫定的なreference.mdに先に移す。最後に本体が自然に妥当な範囲まで軽量化されたかを確認する。一度に全面的に作り直すよりも、この段階的な分割方式の方がリスクが低く、各ステップでSkillが正常に機能し続けていることを確認しやすい。
初めてSkillを書くとき、最もよくある間違いは短すぎることではなく、長すぎることだ。使う可能性のある詳細、あらゆる例外ケース、あらゆる参考資料を一つのSKILL.mdに詰め込み、「とりあえず書いておけば損はない」と考えてしまう。だがこの直感は、Skillの設計原理とは正反対のものだ。
Anthropicの公式ドキュメントはSKILL.mdの長さに明確な目安を示している：本体は500行以内に収め、それを超える内容は独立したファイルに分割すべきだという。これは適当に出された数字ではなく、Skillアーキテクチャそのものに組み込まれた3層の段階的開示（Progressive Disclosure）メカニズムに直接対応している。この3層がどう機能するかを理解して初めて、「どれくらいの長さで書くべきか」という問い自体が、実は間違った方向を向いていることがわかる。
Skillの読み込みは3つの異なる段階に分かれており、各段階で読まれる内容量は大きく異なる。第1層は起動時。ClaudeはSkillごとのYAMLフロントマター——nameとdescriptionフィールドのみを読み込み、Skillあたり数十トークンしか消費しないため、数十のSkillがインストールされたシステムでも起動時の負荷は軽い。
第2層はトリガー時。ユーザーのリクエストがあるSkillのdescriptionに記述された状況と一致したときのみ、ClaudeはそのSkillの完全なSKILL.md本体をコンテキストに読み込む。500行の目安が管理しているのはまさにこの層だ——本体が長いほど、トリガー時に一度に流れ込む内容が増え、コンテキスト内の他の本当に関連性の高い情報を薄めてしまう。
第3層は拡張読み込み。Skill.md内に他のファイル（forms.mdやreference.mdなど）へのリンクがある場合、Claudeはその詳細が実際に必要になったときにのみ読みに行く。Skillがトリガーされたからといって、リンクされたファイルすべてを一度に読み込むわけではない。
ここが最も誤解されやすい点だ：500行の制限はSKILL.md本体に適用されるのであって、Skillが含められる知識の総量に上限があるわけではない。公式ドキュメントが挙げるPDF処理Skillの例では、SKILL.md本体はコアロジックと最もよく使う操作のみを保持し、フォーム入力のようにあまり使われないが詳細が多い内容は独立したforms.mdに移され、ユーザーが実際にフォーム入力を求めたときにのみClaudeがそのファイルを読みに行く。
つまり、一つのSkillが担える知識の総量には事実上上限がなく、制限されているのは「トリガー時に最初の波でコンテキストに流れ込む量」だけだ。この仕組みは、よく整理されたマニュアルのようなものだと考えるといい——まず目次があり、次に該当章、そして最後に付録の詳細仕様がある。読者は些細な詳細を調べるためだけに本全体を最初から最後まで読む必要はない。
開示の第1層は完全にdescriptionフィールドで動作する——Claudeがあるスキルをトリガーするかどうかは、この説明文がユーザーのリクエストの意味と一致するかどうかで判断される。descriptionが曖昧に書かれている場合（例えば「PDF関連の作業を処理する」とだけ書かれている場合）、Claudeはそのスキルが本当に必要な状況でも、トリガーすべきと判断できない可能性が高い。逆に、ユーザーが実際に口にしそうなキーワードや状況説明を具体的に含めて書かれていれば、トリガー精度は明らかに向上する。
これが「SKILL.mdをどれだけ長く書くべきか」が最初に問うべき問いではない理由でもある——descriptionが十分に正確でなければ、本体をどれだけ簡潔にしても意味がない。なぜならClaudeはそもそも本体を読む段階にすら到達しないからだ。
実務的な判断基準は明快だ：SKILL.md本体には高レベルのロジックと最も頻繁に使う操作手順のみを置くべきであり、あるセクションが数百語を超える場合、あるいは「ほとんどの場合は不要だが、少数のケースでは完全な詳細が必要」な内容（特定のエラーコードの処理方法、高度なパラメータ設定など）であれば、それは独立ファイルへの分割のシグナルだ。分割後のファイルはリンクの深さを1階層にとどめることが推奨され、Claudeが一つの詳細を調べるために複数階層の文書を連続してたどる必要がないようにする。
次にSKILL.mdを書く前に、まずdescriptionを的確に仕上げよう——Claudeがひと目で「このリクエストは自分をトリガーすべきか」を判断できるほど具体的にする。次に本体の内容をコアロジックと高頻度の操作範囲に絞り、詳細で低頻度だが分量の多い内容は迷わず独立ファイルに移す。500行は絶対的な天井ではなく、一つの警告サインだ——その分量に達してもまだファイルを分割していないなら、本体はすでに本来担うべきでない役割を背負い始めている証拠である。