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

Claudeが起動時に読み込むのは、各Skillのnameとdescriptionの2フィールドだけです。本文の手順がどれだけ優れていても、この2つが曖昧ならSkillは選ばれません。説明が広すぎれば、関係ないタスクにまで誤発動します。

Skillが期待どおりに呼ばれないとき、確認する順番は決まっています。名前と説明文、上限値、本文の長さ、参照ファイルの置き方です。この記事はその順に、Anthropic公式のSkill authoring best practicesを実例つきで読み解きます。

Skillが呼ばれないなら、まずnameとdescriptionを疑う

nameは最大64文字で、使えるのは小文字・数字・ハイフンのみです。XMLタグと、anthropic・claudeという予約語は入れられません。推奨される語形は動名詞(gerund、動詞+ing)で、「〜すること」を表すと名前だけで役割が伝わります。

descriptionは1,024文字以内で、Skillが何をするかといつ使うかの両方を書きます。Claudeは100を超えるかもしれないSkillの中から、この文だけを手がかりに選びます。

効果的な例は、動作と使う場面を1文に収めています。

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を扱うとき、フォームという語が出たとき)です。公式が避けるべき例として挙げるHelps with documents・Processes data・Does stuff with filesには、後半に当たる情報が1つもありません。

上限値はAPIとClaude Codeで食い違う

同じSKILL.mdでも、読み込む側によって扱いが違います。公式ページを並べると、次の差が出ます。

Claude Codeで名前が一覧に残る一方、説明だけが落ちると、Claudeはキーワードを失って選べなくなります。対処は/doctorで一覧のコストと大きい要因を確かめ、説明の冒頭に最重要の用途を置くことです。予算は設定のskillListingBudgetFraction、1件あたりの上限はskillListingMaxDescCharsで変えられます。

この違いは、手元の検証でも見えます。作業用の空のディレクトリに4つのSKILL.mdを置きました。1つは推奨どおりのprocessing-pdfsです。残りは予約語入りのclaude-helper(説明が一人称)、大文字とアンダースコアのPDF_Tools、説明が1,100文字のlong-descで、いずれもAPIの規則には反します。Claude Code v2.1.287で検証コマンドを走らせた結果が次です。

$ claude plugin validate sk/skills --strict
Validating components in: sk/skills
 
✔ Validation passed

規則違反の3つを含めて、--strictでも通りました。公式はこのコマンドを「frontmatterが解析できないSKILL.mdを見つける」用途で紹介しています。つまり、APIにアップロードするSkillの名前や長さの規則は、ローカルでは自分で確かめる必要があります。

本文はどこまで短くするか

コンテキストウィンドウは、Skillだけが使える場所ではありません。システムプロンプト、会話履歴、他のSkillのメタデータ、実際のリクエストと分け合う共有の資源です。起動時に読まれるのは名前と説明だけですが、SKILL.md本文が選ばれた瞬間から、本文の全トークンが他の情報と競合します。

基本の前提は「Claudeはすでに十分に賢い」ことです。追加するのはClaudeがまだ知らない情報だけにして、1段落ごとに「この説明は本当に要るか」と問い直します。公式の対比例では、pdfplumberの使い方を示す約50トークンの版が正解でした。「PDFとは何か」から語り始める約150トークンの版は、同じ作業を3倍のトークンで頼むことになります。

指示をどこまで具体的に書くかは、タスクの壊れやすさで決めます。

判断の物差しは、崖に挟まれた狭い橋か、障害物のない野原かです。橋なら逸脱が即失敗になるので低い自由度、野原なら多くの経路が成功に届くので高い自由度を選びます。

本文が長くなったら、3層に分けて読ませる

500行を超えそうなSKILL.mdは、段階的開示(progressive disclosure)で割ります。必要なタイミングで必要な情報だけをClaudeに読ませる設計で、読み込みは3層に分かれます。

実務のルールは「SKILL.md本体は500行以内」です。超える内容の割り方は3通りあります。

パターン1: 概要と参照ファイルに分ける

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

パターン2: ドメインごとに分ける

複数の領域を扱うSkillでは、reference/finance.md・reference/sales.mdのように領域別にファイルを置きます。売上の質問ならsales.mdだけが読まれ、財務やマーケティングのデータは読み込まれません。公式の例では、SKILL.mdに領域ごとの案内を並べ、grep -i "pipeline" reference/sales.mdのような検索コマンドまで書いています。

パターン3: 条件のときだけ詳細へ誘導する

基本操作は本文に書き、特定の条件だけ別ファイルへ送ります。「変更履歴の追跡が必要ならREDLINING.mdを参照」と書けば、そのファイルは該当する依頼のときにだけ読まれます。

参照は1階層までにする

見落としやすい落とし穴が、参照ファイルからさらに別の参照ファイルへ飛ぶ「ネストした参照」です。ネストされたファイルに行き当たると、Claudeは全体を読まずにhead -100のようなコマンドで部分的に覗くことがあります。結果として、情報が欠けたまま作業が進みます。

対策は、すべての参照ファイルをSKILL.mdから直接リンクすることです。SKILL.md→advanced.md→details.mdと辿らせず、SKILL.mdからadvanced.md・reference.md・examples.mdへ並列に張ります。100行を超える参照ファイルは、冒頭に目次を置きます。部分読みになっても、目次から全体の範囲が分かります。

Claude Codeでは、圧縮後に残るのは本文の先頭だけ

500行以内という上限とは別に、Claude Codeには本文の長さが効く場面があります。会話が自動で圧縮(auto-compaction)されると、呼び出し済みのSkillは最新の1回分が圧縮の後ろに再添付されます。残るのは各Skillの先頭5,000トークンまでで、再添付されるSkill全体の合計は25,000トークンです。

予算は新しく呼んだSkillから順に埋まるため、1セッションで多くのSkillを使うと、古いものは丸ごと外れます。Claude Codeの公式は、圧縮後は同じSkillを呼び直して全文を戻すこと、重要な指示はSKILL.mdの冒頭近くに置くことを挙げています。参照ファイルへ逃がすかどうかの分け目は、行数だけでなく「毎回守らせたい指示が先頭に収まっているか」でもあります。

命名と分割は、同じ設計判断の両面

descriptionが具体的であるほど、Claudeは的確にSkillを選べます。選ばれたあとにSKILL.md本文が肥大していれば、今度は読み込み後のコンテキスト消費が問題になります。名前と説明で正確に見つけさせ、本文と参照ファイルの分割で読み込み量を絞る。この二段がそろって、多数のSkillを抱える環境でも安定します。Skillsを与えること自体の効果と、モジュール数・複雑さの影響は、ベンチマークSkillsBenchの結果にまとまっています。

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

書く前に評価を作り、モデルごとに確かめる

公式は、長い手順書を書く前に評価を作るよう勧めています。まずSkillなしでClaudeに代表的なタスクを解かせ、失敗や足りない文脈を記録します。そのギャップを突く場面を3つ用意し、Skillなしの成績を基準にして、足りない分だけを最小限の指示で埋めます。想像上の要件を文書化してしまう失敗を、この順序が防ぎます。

指示の磨き込みでは、Skillを作る側と使う側でClaudeのインスタンスを分ける方法が紹介されています。作る側(Claude A)に設計と推敲を任せ、使う側(Claude B)に実作業をさせて、つまずいた箇所をA側へ戻します。Bが想定外の順でファイルを読む、参照を辿らない、同じファイルを何度も開く、といった動きが、構造の見直しどころです。

効果は土台のモデルに左右されるため、複数モデルで使うなら全モデルで試します。

Opusには簡潔な指示で通じても、Haikuにはもう少し詳しい説明が要る場合があります。使うモデルすべてで無理なく動く水準に、指示を寄せておきます。

まとめ

Skillの発見はnameとdescriptionだけで決まり、上限値は読み込む側(APIかClaude Codeか)で違います。APIに出すSkillの規則はローカルの検証では見張られないため、名前と説明文の確認は公開前の作業として残ります。本文が膨らんだら、参照は1階層で直接リンクし、毎回守らせたい指示はSKILL.mdの先頭に置きます。