skill-load-tips

スキルの読み込みに関するヒント

エージェントが本文しか読まない場合の、SKILL.md ファイル向けリファクタリングパターンです。references/ フォルダーは存在しないも同然です。

失敗パターン

大規模なスキルには、詳細なリファレンスファイル（references/*.md）が含まれていることがよくあります。そこには、重要な詳細情報（ARIA パターン全体、使用禁止語のリスト、変更前後の例、アーキタイプなど）が記載されています。一方、SKILL.md の本文はそれらを要約しています。エージェントは本文を読み、「これで十分」と感じて、関連ファイルを読みません。その結果、リファレンスファイルは使われないままになります。

これは、リファレンスのインライン代替アンチパターンです。よく整理されたスキルのパフォーマンスが低下する理由として、最もよく見られるものです。

症状（見分け方）

次のうち2つ以上に当てはまる場合、SKILL.md にこの問題がある可能性があります。

• 本文が250行を超え、参照先のファイルにも記載されているチェックリスト、表、使用禁止語のリストがインラインで記述されています。
• 「Reference Index」／「Files」セクションが、作業手順の後、末尾にあります。
• リファレンスの紹介に、歯切れの悪い表現が使われています。「詳しくは X をお読みください」、「詳細は X をご覧ください」、「X に詳しい情報があります」。
• タスクから必読ファイルへの対応を示す、冒頭の「ルーター」がありません。
• リファレンスファイルが SKILL.md から直接ではなく、別のリファレンスファイルからリンクされています（深いネスト）。
• 100行を超えるリファレンスファイルの冒頭に目次がありません。

4つの修正方法（順番に適用）

修正1 — 冒頭に必読ファイルへのルーターを追加する

スキルの冒頭段落の直後（「Operating Loop」／「Steps」セクションの前）に表を挿入します。この表で、タスクの種類ごとに、そのタスクで必ず読むファイルを示します。

テンプレート：

## Required Reading Router

Match your task to the row. Read the listed files **in full before** producing output. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer, not a substitute.

| Task                                          | MUST read                                                    |
| --------------------------------------------- | ------------------------------------------------------------ |
| [Task type A]                                 | `references/file-a.md`                                       |
| [Task type B]                                 | `references/file-b.md` + `references/file-c.md`              |
| [Task type C]                                 | `references/file-d.md`                                       |

ルーターの直下にReference Indexを配置し、各ファイルに何が含まれているかを1行で説明します。ルーターでエージェントにファイルを読み込むタイミングを伝え、インデックスで読み込むファイルの内容を伝えます。

修正2 — 作業手順に強制的な STOP 指示を追加する

対応するリファレンスファイルがある各手順の末尾に、必ず読むよう指示を加えます。曖昧な表現は命令形に置き換えます。

変更前：

For ARIA component patterns and verification recipes, read `references/accessibility-floor.md`.

変更後：

**STOP. Read `references/accessibility-floor.md` in full before implementing or reviewing any interactive widget.** That file contains the complete ARIA patterns (dialog, combobox, menu, tabs, slider, listbox) and the verification recipes. The inline summary above is a tripwire, not the contract.

STOP 指示には、次の3つのルールがあります。

1. STOP の語を太字にします。視覚的な中断を促すためです。
2. トリガー条件（「インタラクティブウィジェットを実装するとき」「トークンを拡張するとき」など）を明記します。「詳しく知りたい場合」では不十分です。
3. インラインの内容は違反を検出するための目印であり、正式な参照元ではないことを明記します。

修正3 — 重複するインラインの内容を要点だけの目印に削る

SKILL.md の手順に、リファレンスファイルにも記載されている10項目のチェックリストが含まれていると、エージェントはそのチェックリストを読んでリファレンスを読み飛ばします。インラインの内容を2〜3行の「目印」に減らします。読み取り時に違反を検出できるだけの情報を残しつつ、明らかに不完全な内容にします。

変更前（WCAG チェックリストをインラインで10項目記載）：

- Text contrast ≥ 4.5:1 (≥ 3:1 for large text)
- Non-text indicators contrast ≥ 3:1
- Focus visible (2px minimum)
- Keyboard reachable
- Target size ≥ 24×24
- prefers-reduced-motion honored
- Semantic landmarks
- Headings in order
- Form controls labeled
- Errors associated via aria-describedby

変更後（3行の目印と強制的な読み込み指示）：

Gist tripwires — the floor items that catch most slop:

- Text contrast ≥ 4.5:1; focus-visible ≥ 2px on every interactive element.
- Full keyboard reachability; `prefers-reduced-motion` honored.
- Semantic landmarks + heading order; form controls programmatically labeled.

**STOP. Read `references/accessibility-floor.md` in full before implementing or reviewing any interactive widget.** The three bullets above are tripwires, not the contract.

思い切って削ります。インラインのリストとリファレンスが同じ内容を扱っている場合は、必ずリファレンスを優先します。

修正4 — リファレンスの階層を1段にする

Anthropic のドキュメントによると、リファレンス同士がリンクされている場合、エージェントは一部だけを読み込む（head -100）ため、内容を見落とします。すべての references/*.md ファイルは、相互にリンクするのではなく、SKILL.md から直接リンクする必要があります。

悪い例：

SKILL.md → references/advanced.md → references/details.md

良い例：

SKILL.md → references/advanced.md
SKILL.md → references/details.md

また、100行を超えるリファレンスファイルには、冒頭に ## Contents セクションを設けます。そうすれば、一部だけを読み込んでも、内容の範囲がわかります。

アンチパターン

修正のように見えて、そうではないもの：

• 既存のトリガー行に「（重要）」や絵文字を追加する。 エージェントが読み取るのは文体であり、装飾ではありません。必須であることを伝えるには、形容詞ではなく動詞を使います（STOP. Read…）。
• 本文をインラインにしたままにするため、参照を短くする。 目的とは正反対です。本文を短くするほど、参照は長くする必要があります。
• すべての参照ファイルの先頭に「TL;DR」を追加する。 エージェントはTL;DRを読んで本文を読み飛ばします。代わりにContents TOCを使いましょう。要約ではなく、セクション名を記載します。
• 緊急性を示す名前に参照ファイルを変更する（URGENT-read-this.md、MUST-READ.md）。ファイル名を変えても読むかどうかの判断は変わりません。判断を促すのはSKILL.md内のトリガーの文言です。
• SKILL.mdを同じ階層にある多数の小さなファイルに分割する。 SKILL.mdは単一のエントリーポイントです。スキルのファイルをトップレベルに複数作ると、見つけにくくなります。

リファクタリングのチェックリスト

リファクタリングを完了とする前に、書き直したSKILL.mdについて以下を確認してください。

• 必須リーディングのルーターが最初の50行以内（導入／基本理念の後）にある。
• 参照インデックスがルーターの隣にある。
• 対応する参照ファイルがある各操作手順が、**STOP. Read references/X.md …**という指示で終わっている。
• 参照内容と重複するインラインのチェックリストが3項目以下に整理され、「tripwires」または「gist」として明記されている。
• 参照ファイルから別の参照ファイルへのリンクがない（階層は1段のみ）。
• 100行を超える参照ファイルの先頭に## Contentsの目次がある。
• SKILL.mdの本文が500行未満である（Anthropicが推奨する上限）。
• For depth, see XやRead X for moreという表現が残っていない。参照への言及は、ルーター／インデックス（説明的）かSTOP指示（必須）のいずれかになっている。

リファクタリングを実施する方法

1. SKILL.mdとreferences/ディレクトリを並べて開きます。
2. 棚卸し：各参照ファイルと、その内容を一覧にします。
3. 診断：上記の「症状」リストを確認し、該当する項目に印を付けます。
4. 修正1（ルーター＋インデックス）、修正2（STOP指示）、修正3（インライン内容の整理）、修正4（階層のフラット化＋目次の追加）の順に適用します。
5. チェックリストを実行します。未チェックの項目が1つでもあれば、リファクタリングは完了していません。
6. 新しいエージェントのインスタンスに、参照ファイルを必要とするタスクを依頼してテストします。実際にファイルを読むかを確認します。読まない場合は、そのファイルへのSTOP指示が弱すぎます。トリガー条件を強化してください。

使用しない場合

• 新しいスキルをゼロから作成する場合 — skill-best-practicesを使用してください。
• SKILL.mdに触れず、参照ファイル自体だけを編集する場合。
• 参照ファイルがなく、150行未満のスキル（ルーティングするものがありません）。
• AGENTS.md／CLAUDE.mdのリファクタリング — これらには別のルールがあります。agent-md-refactorを使用してください。

要点

A reference file the agent never loads is a reference file that does not exist.
The body of SKILL.md is a dispatcher, not an encyclopedia.
Trim the inline. Force the load. Flatten the depth.