ai-docs

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

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

12本を統合する。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 when there are many, some skills lose their descriptions entirely, which can strip the keywords Claude uses to decide whether a skill applies.

名前は常にロードされるが、数が多いと、いくつかの skill は description を丸ごと失う。そのため、Claude がその skill を使うかを判断する手がかりとなるキーワードが削られることがある。 — large-codebases

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

tool の description

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

Aim for at least 3–4 sentences for each tool description.

ツールの説明は、それぞれ最低でも3〜4文を目安にせよ。

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

4. 命名

対象規則
skillgerund 形（動名詞）を推奨 — processing-pdfs、analyzing-spreadsheets、testing-code。避ける: helper / utils / tools / documents / data
toolサービスや資源で prefix — github_list_prs、slack_send_message。tool search を使うとき特に重要
skill（Claude Code）コマンド名は frontmatter の name（他のコマンドがその名前を使っていないとき）、無ければディレクトリ名（以前の取得で、個人・プロジェクトの skill でも name がコマンド名になった。skills）

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つ添える。

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

「ある時期より前なら旧API」のような記述は必ず陳腐化する。

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

用語を統一する

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

社内の skill から

Anthropic 社内の数百の skill は9種類に分かれ、1種類にきれいに収まるものが最も良い（how-we-use-skills）。書き方の要点は3つ —— 当たり前を書かない（既定でやることを繰り返す skill は価値を足さずに context を足す）、落とし穴（Gotchas）の節を失敗から育てる、description は要約ではなく発火条件として書く。社内で出力品質に最も測れる効果があったのは検証の skill。

Claude 5 世代（Opus 5 / Fable 5。以前の記事）では、例を与えることがかえって探索の範囲を狭めるので、例よりもツール・スクリプト・ファイルの設計（パラメータの表現力）に時間を使う（new-rules-of-context-engineering）。

6. 参照の張り方

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

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

2つの規則:

  1. 参照は SKILL.md から1階層だけ。 ネストされた参照は、Claude が head -100 などで部分読みするため情報が欠ける
  2. 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 へ）

バックリンク