Agent Skillsの命名規則と段階的開示の設計原則

Claudeが起動時に読み込むのは、多数のSkillが並ぶ中の各Skillのnameとdescriptionの2フィールドだけです。本文の手順がどれだけ優れていても、この2つが曖昧ならSkillは選ばれず、説明が広すぎれば関係ないタスクにまで誤発動します。この記事は、Anthropic公式のSkill authoring best practicesが定める命名規則・description設計・SKILL.md本体の分割方針(段階的開示)を、具体例つきで扱います。

Skillの命名規則とは何か

Skillの命名規則とは、nameフィールドに使える文字種と推奨される語形のルールです。nameは最大64文字、使えるのは小文字・数字・ハイフンのみで、XMLタグやanthropic・claudeという予約語は使えません。この制約はAnthropic製・カスタムSkillの両方に共通です。

推奨される語形は動名詞(gerund、動詞+ing)です。processing-pdfs・analyzing-spreadsheets・managing-databasesのように「〜すること」を表す形にすると、そのSkillが何をする活動なのかが名前だけで伝わります。名詞句(pdf-processing)や動詞始まりの表現(process-pdfs)も許容されますが、コレクション内で語形を統一することが重要です。

避けるべきはhelper・utils・toolsのような曖昧な名前、documents・data・filesのような広すぎる名前、そして予約語を含むanthropic-helperのような名前です。複数のSkillを管理する組織では、この命名規則がバラバラだと一覧を見ただけでは各Skillの役割が分からなくなり、参照・検索・保守のすべてで摩擦が生まれます。

description設計 — Claudeが選ぶための唯一の手がかり

descriptionフィールドはSkill選択の判断材料そのものです。1,024文字以内で、そのSkillが何をするかといつ使うべきかの両方を含める必要があります。

効果的なdescriptionの例です。

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

このように「何をするか(PDF抽出・フォーム入力・結合)」と「いつ使うか(PDFファイルを扱うとき、PDFやフォームという語が出たとき)」の両方を1文に詰め込みます。「Helps with documents」「Processes data」のような曖昧な説明は、Claudeがどんな場面でこのSkillを選べばいいのか判断できず、実質的に発見されないSkillになります。

SKILL.mdを簡潔に保つ理由

コンテキストウィンドウは、あなたのSkillだけが占有する場所ではありません。システムプロンプト・会話履歴・他のSkillのメタデータ・実際のリクエスト内容と共有する公共の資源です。Skillが起動時に読み込まれるのは名前と説明だけとはいえ、いったんSKILL.md本文が選ばれて読み込まれると、その中のすべてのトークンが会話履歴や他の情報と競合し始めます。

「Claudeはすでに十分に賢い」という前提を置いて書くのが基本方針です。追加するのはClaudeがまだ知らない情報だけで、「この説明は本当に要るか」「Claudeが知っている前提でよいのではないか」を1段落ごとに問い直します。たとえばPDFからテキストを抽出する手順を書くとき、「PDFとは何か」「ライブラリとは何か」から説明を始める必要はありません。使うライブラリ名と最小のコード例だけを書けば、それだけでClaudeには十分です。PDFの一般的な説明を足すごとに、そのぶん会話履歴や他のSkillの情報を押し出すことになります。

指示の自由度をタスクの性質に合わせる

Skillの指示は、どこまで具体的に書けばよいのでしょうか。公式ベストプラクティスは、タスクの壊れやすさと変動性に応じて自由度を3段階で調整するよう勧めています。

自由度が高い場合(文章ベースの指示)

複数のアプローチが正解になり得るタスクに向きます。コードレビューのように、状況に応じて判断が変わる作業では「構造を分析する」「バグの可能性を確認する」といった大まかな方針を示し、具体的な進め方はClaudeに委ねます。

自由度が中程度の場合(パラメータ付きの疑似コード)

好ましいパターンは存在しつつも多少の変動を許容できるタスクに向きます。レポート生成のように、テンプレートの骨格は決まっているが出力形式や含める要素を調整したい場合です。

自由度が低い場合(具体的なスクリプト)

操作が壊れやすく一貫性が最優先されるタスクに向きます。データベースのマイグレーションのように、決まった手順を一字一句そのまま実行する必要がある作業では、「このコマンドをそのまま実行し、フラグを追加しない」という具体的な制約まで書きます。

崖に挟まれた狭い橋(低自由度、逸脱が即失敗につながる)と、障害物のない開けた野原(高自由度、多くの経路が成功にたどり着く)のどちらに近いタスクかを見極めることが、自由度を決める判断基準になります。

SKILL.mdの構造 — 段階的開示という設計原則

段階的開示(progressive disclosure)とは、Claudeが必要なタイミングで必要な情報だけを読み込む設計です。起動時に読まれるのは全Skillのnameとdescriptionだけ(第1層)、そのSkillが選ばれるとSKILL.md本文が読み込まれ(第2層)、本文からリンクされた参照ファイルは実際に必要になったときだけ読み込まれます(第3層)。

この設計から導かれる実務ルールが「SKILL.md本体は500行以内に収める」というものです。超えそうな内容は、参照ファイルへ分割します。分割パターンは主に3つあります。

パターン1: 概要+参照ファイル型

SKILL.mdにクイックスタートだけを書き、フォーム入力の詳細はFORMS.md、APIリファレンスはREFERENCE.mdのようにリンクで逃がします。Claudeは必要なファイルだけを開きます。

パターン2: ドメイン別分割型

複数の領域を扱うSkillでは、reference/finance.md・reference/sales.mdのようにドメインごとにファイルを分けます。売上の質問にはsales.mdだけを読み、財務やマーケティングのデータは読み込まれません。トークン消費を領域単位で絞り込める設計です。

パターン3: 条件付き詳細型

基本操作をSKILL.md本文に書き、「変更履歴の追跡が必要な場合はREDLINING.mdを参照」のように、特定条件のときだけ詳細ファイルへ誘導します。

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

段階的開示には見落としやすい落とし穴があります。参照ファイルからさらに別の参照ファイルへリンクする「ネストした参照」です。Claudeはネストされたファイルに遭遇すると、全体を読み込む代わりにhead -100のようなコマンドで部分的にプレビューすることがあり、結果として情報が欠落したまま処理が進みます。

対策は単純で、すべての参照ファイルをSKILL.mdから直接リンクすることです。SKILL.md→advanced.md→details.mdのような多段リンクは避け、SKILL.mdからadvanced.md・reference.md・examples.mdへそれぞれ直接リンクする構成にします。100行を超える参照ファイルには冒頭に目次を置くことも推奨されており、Claudeが部分読みをした場合でも、目次を見れば全体の情報範囲を把握できます。

命名とファイル分割はセットで設計する

命名規則と段階的開示は独立したルールに見えますが、実際には1つの設計判断の両面です。descriptionが具体的であるほどClaudeは的確にSkillを選べますが、選ばれた後のSKILL.md本文が肥大化していれば、今度は「読み込まれた後のコンテキスト消費」が問題になります。名前と説明で正確に「発見」させ、本文と参照ファイルの分割で「読み込み量」を絞る、という二段階の設計が揃って初めて、多数のSkillを抱える環境でも安定して機能します。

Claude CodeのSkillsも同じSKILL.mdの構造を土台にしていますが、frontmatterの必須項目や呼び出しのスコープはAPI経由のSkillとは別物です。Claude Code側の配置場所・呼び出し方の詳細はClaude Code Skills完全ガイドにまとめています。またSkillsをエージェントに組み込む設計思想そのものはAgent Skillsとは何かで扱っており、評価駆動でツールの挙動を検証する考え方はエージェント向けツール設計の原則とも重なります。

モデルをまたいだテストが必要な理由

Skillはモデルへの追加機能なので、効果は土台となるモデルの性能に依存します。HaikuではSkillの説明が十分に具体的かどうか、SonnetではSkillの指示が明快で効率的か、Opusでは説明が冗長になりすぎていないか、それぞれ確認する観点が異なります。Opusでは簡潔な指示で十分でも、Haikuではもう少し詳しい説明が必要になるケースがあり、複数モデルで使う予定のSkillは、全モデルで無理なく動く水準の指示に調整しておくことが推奨されています。

公開前チェックリスト

Skillを共有する前に、公式ベストプラクティスは次の観点の確認を挙げています。

まとめ

Skillの発見精度はnameとdescriptionの2フィールドだけで決まり、動名詞の命名パターンと「何を・いつ」を明記した説明文が土台になります。本文が肥大化する場合は、参照ファイルへの分割(概要型・ドメイン別型・条件付き型)で段階的開示を機能させ、参照は必ずSKILL.mdから1階層で直接リンクします。命名と分割のどちらかが崩れると、Skillは存在していても実質的に使われないままになります。