Claude Skills のルール｜SKILL.md 命名と 500 行制限の書き方

claude skills rules とは — Skills を成立させる 4 種のルール

「claude skills rules」という検索語の本命は、Claude Agent Skills を作るときに守るべき 公式ルールの集合体 です。Skills は SKILL.md という単一ファイルの YAML フロントマターとマークダウン本文だけで動く軽量な拡張機構で、.claude/skills/<name>/SKILL.md を置けば Claude が自動で発見してくれます。

ただし「動く」と「Claude が正しく発見・実行してくれる」は別問題です。Anthropic のSkill authoring best practices は、フロントマターの形式バリデーション・命名・description の人称・本文サイズ・参照階層という 5 領域でルールを定めており、これを踏むだけで Skill の発見率と実行精度が大きく変わります。

本記事はこのルール群を、踏み外しやすい順に整理します。先に挙げた 4 軸(メタデータ制約・記述スタイル・物理サイズ・参照階層)に加えて、評価駆動開発の規律まで含めて 1 本で押さえられる構成です。

SKILL.md フロントマターのバリデーションルール

SKILL.md の冒頭に置く YAML フロントマターは、Claude 側のローダーが形式バリデーションを掛けます。必須フィールドは name と description の 2 つだけですが、それぞれに厳格なルールがあります。

name の制約は次の 4 点です。

1. 最大 64 文字
2. 小文字英字・数字・ハイフン - のみ(大文字・アンダースコア・スペース不可)
3. XML タグを含めない
4. 予約語 anthropic claude を含めない

description の制約は 3 点で、最大 1024 文字、非空必須、XML タグ不可です。description は Claude が 100 個以上ある Skill から該当 Skill を選ぶときに参照する唯一のサマリ なので、形式制約を満たしたうえで「何をするか」と「いつ使うか」の両方を含める必要があります。

これらは Skills overview の Skill structure 節と Best practices の Naming conventions 節で繰り返し明記されており、違反すると Skill が読み込まれない・発見されないという致命的な結果を招きます。

命名規則 — 動名詞形と曖昧名禁止

name フィールドのフォーマットを満たしたうえで、Anthropic は命名スタイルとして 動名詞形(gerund form) を推奨しています。動詞 + ing で「その Skill が提供する能力」を端的に示す形です。

公式推奨例:

1. processing-pdfs
2. analyzing-spreadsheets
3. managing-databases
4. testing-code
5. writing-documentation

代替として、名詞句(pdf-processing / spreadsheet-analysis)や動詞型(process-pdfs / analyze-spreadsheets)も許容されます。一方で避けるべきは次のパターンです。

• 曖昧名: helper / utils / tools
• 過度に汎用: documents / data / files
• 予約語混入: anthropic-helper / claude-tools
• コレクション内で一貫しないパターン

命名が揃っていると、Claude 側が Skill を発見しやすいだけでなく、ドキュメントや会話で参照したときに何の Skill かが一目で分かります。100 個入れたときに効くのはこの一貫性です。

description は三人称で書く — 発見性を決定づける作法

Skills の発見性で最も致命的なミスは、description を一人称や二人称で書いてしまうことです。Anthropic 公式は 「常に三人称で書け(Always write in third person)」 を Warning ブロックで強調しています。

理由は明快で、description は Claude の system prompt に注入される文字列だからです。視点が混在すると Claude が「誰が何をする Skill か」を誤読し、選択精度が落ちます。

• ✓ 良い例: 「Processes Excel files and generates reports」
• ✗ 悪い例: 「I can help you process Excel files」
• ✗ 悪い例: 「You can use this to process Excel files」

加えて、description には 「何をするか」と「いつ使うか」の両方 を入れる必要があります。公式 PDF Processing Skill の 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.

前半が機能、後半が発火条件です。「Helps with documents」「Processes data」「Does stuff with files」のような曖昧 description は Skill 選択時の判断材料にならず、Claude が無視します。

SKILL.md 本文の 500 行ルールと Progressive Disclosure

name と description のメタデータは常時 system prompt に展開されますが、SKILL.md 本文は Skill が発火したときだけ Claude が読み込みます。それでも一度読み込まれれば全トークンが context を消費するため、Anthropic は SKILL.md 本文を 500 行以下に保つ ことを公式の上限目安として定めています。

500 行を超えたら別ファイルに分割し、SKILL.md から参照リンクで繋ぐのが Progressive Disclosure(段階的開示)です。reference/finance.md reference/sales.md のようにドメイン別に切り出すと、ユーザーが売上について聞いた瞬間に Claude は finance.md だけを bash 経由で読み、sales.md は context にロードされません。これが「100 個入れても context が膨らまない」と言われる仕組みの実体です。

実装上のポイントは次の 3 つです。

1. SKILL.md 本文は 500 行以下、超えたら分割
2. 分割先は domain や feature 単位(ファイル名で内容が分かる粒度)
3. SKILL.md から見て 参照は 1 階層だけ深い場所 に置く

3 点目が次節のテーマです。

参照は 1 level deep に揃える — 多段ネスト禁止

Anthropic のドキュメントには「Avoid deeply nested references」という独立した節があり、参照ファイルから別の参照ファイルへチェーンする多段構造を明確に否定しています。

理由は実装側の都合で、Claude は参照されたファイルを head -100 などで部分読みすることがあるため、ネストが深いと「途中までしか読めず本文に辿り着けない」状態が発生します。

• ✗ 悪い例: SKILL.md → advanced.md → details.md(本体は details.md)
• ✓ 良い例: SKILL.md から advanced.md / reference.md / examples.md に直接リンクし、本文をそこに置く

加えて、参照ファイル自体が 100 行を超えるなら 冒頭に目次(table of contents) を置くルールも公式で定められています。Claude が部分読みしたときでも、目次セクションが見えていれば「この情報はこの位置にある」と判断できます。

ファイルパスと用語の規律 — forward slash と一貫性

実装段階で踏み外しやすいルールが 2 つあります。

1 つ目は ファイルパスは forward slash(/)で統一 すること。Skills は Unix 系のコード実行環境で動くため、Windows 風の scripts\helper.py はエラーになります。scripts/helper.py reference/guide.md の表記で揃えます。

2 つ目は 用語の一貫性。同じ概念を指す語を文書内で混在させると Claude が混乱します。

• 良い例(一貫): 「API endpoint」のみ、「field」のみ、「extract」のみ
• 悪い例(混在): 「API endpoint」「URL」「API route」「path」を混ぜる

加えて、時間依存情報(「2025 年 8 月までは旧 API、それ以降は新 API」など)を本文に書かないルールがあります。時間で陳腐化する情報は <details> でくくった「Old patterns」セクションに退避し、現行の正しい手順だけを本文に残します。

MCP ツール参照は完全修飾名で書く

Skills 内から MCP(Model Context Protocol)ツールを呼び出す場合、Anthropic 公式は ServerName:tool_name の完全修飾形式 を必須としています。

• ✓ 良い例: Use the BigQuery:bigquery_schema tool to retrieve table schemas.
• ✓ 良い例: Use the GitHub:create_issue tool to create issues.
• ✗ 悪い例: Use bigquery_schema / Use create_issue(サーバー名なし)

複数の MCP サーバーが同時に有効な環境では、サーバー名なしの参照は「tool not found」エラーで失敗します。Skills が複数環境で動く前提なら、最初から完全修飾で書くのが安全です。

評価駆動開発 — eval を先に書くルール

Skills の品質ルールでもう一つ重要なのが、ドキュメントを書く前に評価(evaluation)を先に作る ことです。Anthropic の Best practices は「Build evaluations first」という節を独立で立てており、次の 5 ステップを推奨しています。

1. Skill なしで代表的タスクを Claude に解かせ、失敗箇所を特定
2. 3 件の評価シナリオを作成して gap をテスト化
3. Skill なしのベースラインを測定
4. 最小限の SKILL.md を書いて gap を埋める
5. 評価を回し、ベースラインと比較しながら改善

eval を後回しにすると「想像で書いたルール」が増え、実際の問題を解決しない肥大化した Skill になります。最低 3 シナリオを先に書き、Haiku / Sonnet / Opus の 3 モデルで効果を確認するのが公式チェックリストの最終項目です。

まとめ — ルールを満たした Skill だけが 100 個並べても効く

Claude Skills のルールは、形式バリデーション(name 64 文字・description 1024 文字)から始まり、命名(動名詞形)・記述スタイル(三人称・トリガー明記)・物理サイズ(500 行)・参照階層(1 level deep)・用語の一貫性・MCP 完全修飾・評価駆動開発まで多層に渡ります。

これらは個別に見ると小さな規約ですが、満たさないと Claude が Skill を発見できない・読み切れない・選択しない という形で全て表面化します。100 個並べても context が膨らまずに動くという Skills の魅力は、書き手側がこのルールを揃えているから成立する設計です。

出典: Skill authoring best practices(Anthropic 公式) / Agent Skills overview