エージェントに読ませる文書の書き方 — 結局どうすればいいか

10本を統合する。CLAUDE.md も skill も rule も tool description も、「エージェントに読ませる文書」という同じ種類のものであり、共通の規範がある。

1. 人間向けの文書とどこが違うか

3点で違う。

	人間向け	エージェント向け
コスト	読まなければゼロ	context に載った瞬間から全トークンが他と競合する
発見のされ方	目次を見て探す	`description` との一致で選ばれる。ここで外れたら本体は読まれない
前提知識	読者によって違う	すでに非常に賢い。説明しすぎが害になる

The context window is a public good. — agent-skills-best-practices context window は公共財である。

デフォルトの前提を変える必要がある:

Claude はすでに非常に賢い。 以下を自問する。「Claude はこの説明を本当に必要としているか？」「これは Claude が知っていると仮定できるか？」 「この段落はトークンコストに見合うか？」

2. 最初に決めるのは「いつロードされるか」

中身より先に、置き場所で決まる。 同じ内容でもコストがまったく違う。

置き場	ロード	コスト
CLAUDE.md	毎セッション全文	毎リクエスト
`.claude/rules/`（`paths` なし）	毎セッション	毎リクエスト
`.claude/rules/`（`paths` あり）	該当ファイルを読んだときだけ	そのときだけ
skill の `description`	毎セッション	約100トークン
skill の本体	起動時のみ	そのときだけ
skill の参照ファイル	読まれたときだけ	読むまでゼロ
`disable-model-invocation: true` の skill	呼ぶまで一切なし	ゼロ

判断:

毎セッション必ず要る（ビルドコマンド、規約、「常に X せよ」）
  → CLAUDE.md（200行以内）
 
コードベースの一部にしか関係しない
  → .claude/rules/ に paths: を付ける
 
多段の手順・参照資料
  → skill
 
副作用がある（deploy、commit、送信）
  → skill + disable-model-invocation: true（context コストがゼロになる）

@path import の誤解に注意:

Splitting into @path imports helps organization but doesn’t reduce context, since imported files load at launch. @path の import に分割すると整理には役立つが、context は減らない。import されたファイルは起動時にロードされるからである。

整理にはなるが削減にはならない。 削減したいなら paths か skill。

3. `description` が最も重要

skill も tool も、description で選ばれる。本体の質は二の次。

skill の description

pay special attention to the name and description. Claude will use these when deciding whether to trigger the skill. name と description には特に注意を払え。Claude は skill を起動するかどうかの判断にこれらを使う。

規則:

必ず三人称で書く。 system prompt に注入されるので視点が混ざると discovery に問題が出る
- ✅ Processes Excel files and generates reports
- ❌ I can help you process Excel files / You can use this to...
「何をするか」と「いつ使うか」の両方を入れる
主要ユースケースを先頭に置く。 description + when_to_use は 1,536 文字で切られる
100個以上から選ばれる前提で、選択に足る詳細を 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.
 
# ❌
description: Helps with documents

切り詰めの罠（large-codebases）:

Names always load, but descriptions are shortened when there are many, which can strip the keywords Claude uses to decide whether a skill applies. 名前は常にロードされるが、数が多いと description は短縮される。そのため、Claude がその skill を使うかを判断する手がかりとなるキーワードが削られることがある。

一覧の予算は context window の 1%。溢れると呼ぶ頻度が低い skill から description が落ちる。 → description は短く、リクエストに含まれそうな語を先頭に。

tool の description

skill と同じ原則だが、要求される長さが違う。

Aim for at least 3–4 sentences for each tool description. ツールの説明は、それぞれ最低でも3〜4文を目安にせよ。

書くべき4点: 何をするか / いつ使うべきでないか / 各パラメータの意味 / 返さないもの。

4. 命名

対象	規則
skill	gerund 形（動名詞）を推奨 — `processing-pdfs`、`analyzing-spreadsheets`、`testing-code`。避ける: `helper` / `utils` / `tools` / `documents` / `data`
tool	サービスや資源で prefix — `github_list_prs`、`slack_send_message`。tool search を使うとき特に重要
skill（Claude Code）	コマンド名はディレクトリ名から来る（`name` は表示名。plugin だけ例外）

5. 本体の書き方

簡潔さが最優先

Keep the body itself concise. Once a skill loads, its content stays in context across turns, so every line is a recurring token cost. State what to do rather than narrating how or why. 本体は簡潔に保て。skill はいったんロードされると、その内容がターンをまたいで context に残り続けるため、1行ごとが繰り返し発生するトークンコストになる。やり方や理由を語るのではなく、何をすべきかを述べよ。

skill は一度ロードされると、そのセッション中ずっと居座る。 だから1行1行が繰り返しコストになる。

目安: SKILL.md は 500行未満。CLAUDE.md は 200行未満。

自由度をタスクの壊れやすさに合わせる

agent-skills-best-practices の最も応用の効く判断軸。

自由度	形式	使うとき
High	文章による指示	複数のアプローチが妥当 / 判断が文脈依存
Medium	擬似コード、パラメータ付きスクリプト	推奨パターンはあるが変動も許容
Low	具体的なスクリプト、パラメータほぼなし	操作が壊れやすい / 一貫性が critical / 手順が固定

比喩: Claude を道を進むロボットと考える。両側が崖の細い橋なら安全な道は1つしかないので、正確な指示とガードレールを与える。危険のない広い野原なら多くの道が成功に至るので、方向だけ示して最良のルートは任せる。

選択肢を出しすぎない

「pypdf でも pdfplumber でも PyMuPDF でも…」ではなく、デフォルトを1つ示し、逃げ道を1つ添える。

時間依存の情報を書かない

「2025年8月より前なら旧API」のような記述は必ず陳腐化する。

代わりに「Current method」と、<details> で畳んだ「Old patterns」節に分ける。

用語を統一する

“API endpoint” / “URL” / “API route” / “path” を混ぜない。

6. 参照の張り方

progressive disclosure を効かせるための構造。

my-skill/
├── SKILL.md           コアは痩せさせる。ナビゲーションに徹する
├── FORMS.md           フォームを埋めるときだけ読まれる
├── REFERENCE.md       詳細な API リファレンス
└── scripts/
    └── validate.sh    実行するだけ。コードは context に載らない

2つの規則:

参照は SKILL.md から1階層だけ。 ネストされた参照は、Claude が head -100 などで部分読みするため情報が欠ける
100行を超える参照ファイルには先頭に目次を置く。 部分読みでも全体像が見える

スクリプトを同梱するのは context 戦略でもある:

Claude can run this script without loading either the script or the PDF into context. Claude はスクリプトも PDF も context にロードせずにこのスクリプトを実行できる。

Only its output consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code on the fly. トークンを消費するのは出力だけであり、そのぶんスクリプトは同等のコードを Claude にその場で生成させるよりはるかに効率的である。

帰結: 同梱コンテンツの量に実質的な上限がない。 使わなければコストゼロなので、包括的な API ドキュメントも大きなデータセットも入れてよい。

7. compaction を意識した配置

context-window の指摘が、書き方に直接効く。

Truncation keeps the start of the file, so put the most important instructions near the top of SKILL.md. 切り詰めではファイルの先頭が残るので、最も重要な指示は SKILL.md の冒頭近くに置け。

compaction 後、skill の本体は 1本 5,000 トークンで切り詰められ、合計 25,000 トークンの予算を古い順に埋める。

さらに:

	compaction 後
プロジェクトルートの CLAUDE.md、`paths` なしの rule	再注入される
`paths:` を持つ rule	失われる（該当ファイルを再度読むまで）
ネストした CLAUDE.md	失われる（同上）

→ compaction を跨いで確実に効かせたいルールは、paths: を外してプロジェクトルートの CLAUDE.md に置く。

8. 「指示」と「強制」を区別する

これを混同すると、守られないルールを書き続けることになる。

Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead. — memory Claude はそれらを強制される設定ではなく context として扱う。Claude の判断によらず動作をブロックしたいなら、代わりに PreToolUse hook を使え。

An instruction like “never edit .env” in CLAUDE.md or a skill is a request, not a guarantee. — features-overview CLAUDE.md や skill に書いた「.env は絶対に編集するな」という指示はお願いであって、保証ではない。

さらに CLAUDE.md の届き方も明かされている:

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. CLAUDE.md の内容は、system prompt の一部としてではなく、system prompt の後に置かれる user メッセージとして届けられる。

必要なもの	手段
振る舞いを導きたい	CLAUDE.md / skill / rule
必ず守らせたい	`PreToolUse` hook（exit code 2）
system prompt レベルに置きたい	`--append-system-prompt`（毎回渡す必要があるのでスクリプト向き）

9. 書く前に eval を作る

agent-skills-best-practices の最も強い規範。

Create evaluations BEFORE writing extensive documentation. 大量のドキュメントを書く「前」に evaluation を作れ。

1. ギャップを特定  skill なしで代表タスクを実行させ、失敗を記録
2. eval を作る     そのギャップを突く3シナリオ
3. ベースラインを測る
4. 最小限の指示を書く  ギャップを埋め eval を通す分だけ
5. 反復する

「最小限」が要点。 eval がないと、どこまで書けば足りるか分からず書きすぎる。書きすぎは context コストとして毎回跳ね返る。

Claude A / Claude B パターン

Skill 開発は Claude 自身とやるのが最も効果的。

Claude A — skill を設計・改良する相棒
Claude B — skill を読んで実タスクをこなす別インスタンス

1. skill なしで Claude A とタスクをやり切り、自分が繰り返し提供している情報に気づく
2. 再利用可能なパターンを特定する
3. Claude A に skill 化を依頼する
4. 冗長さをレビューして削らせる
5. 情報アーキテクチャを改善させる
6. Claude B（fresh instance）でテストする
7. Claude B の躓きを具体的に Claude A に持ち帰る

fresh instance でテストする理由（skills が明示）:

A fresh session matters because leftover context from authoring the skill will mask gaps in the written instructions. まっさらなセッションで試すことが重要なのは、skill を書いたときの context が残っていると、書かれた指示の抜けが覆い隠されてしまうからである。

Claude の読み方を観察する

観察	意味
想定外の探索順	構造が直感的でない
参照を辿らない	リンクが目立たない
同じファイルばかり読む	SKILL.md 本体に入れるべき
一度も読まれないファイル	不要か、signal が弱い

10. アンチパターン

agent-skills-best-practices の列挙が実用的。

アンチパターン	直し方
Windows 形式のパス（`scripts\helper.py`）	常に forward slash
選択肢を出しすぎる	デフォルト1つ + 逃げ道1つ
スクリプトで Claude に判断を先送りする	”solve, don’t defer”。エラーは明示的に処理する
voodoo constants（`TIMEOUT = 47 # Why 47?`）	値の根拠をコメントに残す
MCP ツールを短縮名で書く	完全修飾名（`BigQuery:bigquery_schema`）

11. 書いた後に見直すこと

モデルが良くなると、書いたものが害に変わる。

Skills developed for prior models are often too prescriptive for Claude Fable 5 and can degrade output quality. Review and consider removing older instructions if default performance is better. — prompting-claude-fable-5 **以前のモデル向けに作った skill は、Claude Fable 5 には指示が細かすぎることが多く、出力品質を下げうる。**既定の性能のほうが良いなら、古い指示を見直して削ることを検討せよ。

instructions that worked around an older model’s limitation may become overhead once a newer model handles the case on its own. For example, a rule that forces single-file refactors can be deleted once the limitation is gone. — large-codebases 古いモデルの制約を回避するための指示は、新しいモデルがその状況を自力で扱えるようになると単なるオーバーヘッドになる。たとえば「リファクタリングは1ファイルずつ」と強制するルールは、その制約が消えれば削除できる。

見直しの習慣（large-codebases が3つ挙げている）:

pull request でレビューする — CLAUDE.md の編集も文書変更として扱う
大きなモデルリリースの後に見直す
Stop hook で更新を提案させる — transcript のパスを受け取れるので、露呈したギャップが新鮮なうちに

12. チェックリスト

置き場を決める
  □ 毎セッション要るか → CLAUDE.md（200行以内）
  □ 一部のファイルだけか → rules に paths:
  □ 手順・参照資料か → skill
  □ 副作用があるか → disable-model-invocation: true
 
description を書く
  □ 三人称か
  □ 「何をするか」と「いつ使うか」の両方があるか
  □ 主要ユースケースが先頭にあるか（1,536文字で切られる）
  □ リクエストに含まれそうな語を使っているか
 
本体を書く
  □ 500行（skill）/ 200行（CLAUDE.md）以内か
  □ 「なぜ」ではなく「何をするか」を書いているか
  □ タスクの壊れやすさに自由度を合わせたか
  □ 選択肢を出しすぎていないか（デフォルト1つ + 逃げ道1つ）
  □ 時間依存の表現がないか
  □ 重要な指示が先頭にあるか（compaction で切り詰められる）
 
参照を張る
  □ 1階層だけか
  □ 100行超の参照に目次があるか
  □ スクリプトで置き換えられるものはないか
 
検証する
  □ 書く前に eval を作ったか
  □ fresh session でテストしたか
  □ どのファイルが読まれ、どれが読まれないか観察したか
 
見直す
  □ モデルリリース後に、不要になった指示を削ったか
  □ 「必ず守らせたい」ものが指示のままになっていないか（→ hook へ）

ai-docs

エクスプローラー

エージェントに読ませる文書の書き方

エージェントに読ませる文書の書き方 — 結局どうすればいいか

1. 人間向けの文書とどこが違うか

2. 最初に決めるのは「いつロードされるか」

3. `description` が最も重要

skill の description

tool の description

4. 命名

5. 本体の書き方

簡潔さが最優先

自由度をタスクの壊れやすさに合わせる

選択肢を出しすぎない

時間依存の情報を書かない

用語を統一する

6. 参照の張り方

7. compaction を意識した配置

8. 「指示」と「強制」を区別する

9. 書く前に eval を作る

Claude A / Claude B パターン

Claude の読み方を観察する

10. アンチパターン

11. 書いた後に見直すこと

12. チェックリスト

グラフビュー

目次

バックリンク

ai-docs

エクスプローラー

エージェントに読ませる文書の書き方

エージェントに読ませる文書の書き方 — 結局どうすればいいか

1. 人間向けの文書とどこが違うか

2. 最初に決めるのは「いつロードされるか」

3. description が最も重要

skill の description

tool の description

4. 命名

5. 本体の書き方

簡潔さが最優先

自由度をタスクの壊れやすさに合わせる

選択肢を出しすぎない

時間依存の情報を書かない

用語を統一する

6. 参照の張り方

7. compaction を意識した配置

8. 「指示」と「強制」を区別する

9. 書く前に eval を作る

Claude A / Claude B パターン

Claude の読み方を観察する

10. アンチパターン

11. 書いた後に見直すこと

12. チェックリスト

グラフビュー

目次

バックリンク

3. `description` が最も重要