Claude API スキルドキュメントの大規模整備：`max_tokens` デフォルト値の刷新と Models API の統合

Claude API スキルドキュメント全体にわたって、max_tokens のデフォルト値が実用的な値へ引き上げられ、Models API を活用したライブなモデル能力検索の仕組みが追加された。あわせて各言語SDKのコードサンプルが現行APIに追従する形で修正されている。

背景

スキルドキュメント群は、Claude APIを使うエージェントが参照するリファレンスとして機能している。これまでのコードサンプルには max_tokens: 1024 というプレースホルダー的な値が各所に残っており、実際のユースケースではトークン上限に達して出力が途中で打ち切られるリスクがあった。またモデルのコンテキストウィンドウや対応機能を確認するには静的なテーブルしか存在せず、最新の情報を動的に取得する手段がドキュメントに示されていなかった。

さらに、各言語SDKのAPIが進化する中で、コードサンプルが旧来の記述パターン（content[0].text への直接アクセスなど）のままになっているケースも複数存在していた。

技術的な変更

max_tokens デフォルト値の統一

max_tokens の不適切なデフォルト値が、リクエスト種別に応じた実用的な値へ統一された。 SKILL.md に追加されたガイドラインでは、値の選択基準が明示されている。

変更後のポリシーは次のとおり:

• 非ストリーミングリクエスト: ~16000（SDKのHTTPタイムアウトを回避できる範囲で余裕を持たせる）
• ストリーミングリクエスト: ~64000（タイムアウトの制約がないためモデルに十分な余地を与える）
• 分類など短い出力が確実な場合のみ: ~256 などの小さな値

このポリシーに基づき、Python・TypeScript・Go・Java・Ruby・PHP・curl の全サンプルで 1024 や 4096 といった値が 16000 または 64000 へ書き換えられた。

Models API によるライブ能力検索の追加

shared/models.md に「Programmatic Model Discovery」セクションが新設され、GET /v1/models / GET /v1/models/{id} を使ったランタイムでのモデル能力検索の方法が文書化された。

Python での利用例:

m = client.models.retrieve("claude-opus-4-6")
m.id                 # "claude-opus-4-6"
m.display_name       # "Claude Opus 4.6"
m.max_input_tokens   # context window (int)
m.max_tokens         # max output tokens (int)

# capabilities は非型付きのネストされた dict — ブラケットアクセスで辿る
caps = m.capabilities
caps["image_input"]["supported"]                       # vision
caps["thinking"]["types"]["adaptive"]["supported"]     # adaptive thinking
caps["effort"]["max"]["supported"]
caps["structured_outputs"]["supported"]
caps["context_management"]["compact_20260112"]["supported"]

# 全モデルをフィルター — ページオブジェクトを直接イテレート（自動ページネーション）
[m for m in client.models.list()
 if m.capabilities["thinking"]["types"]["adaptive"]["supported"]
 and m.max_input_tokens >= 200_000]

トップレベルフィールド（id・display_name・max_input_tokens・max_tokens）は型付き属性として提供され、capabilities は dict としてブラケットアクセスで辿る。APIはすべてのモデルについて supported: true/false のフル機能ツリーを返すため、.get() ガードなしにブラケットチェーンが安全に使える。

SKILL.md のサポートエンドポイント一覧にも Models API（GET /v1/models・GET /v1/models/{id}）が追記され、「コンテキストウィンドウは？」「このモデルはvisionに対応しているか？」といった質問には静的テーブルではなくライブ検索を使うよう明示的なガイダンスが加えられた。

各言語SDKのコードサンプル修正

コンテンツブロックへのアクセスパターンが、型安全な書き方に統一された。 これまで response.content[0].text のように先頭ブロックへ直接アクセスしていたサンプルは、type フィールドで判別してから .text を読み出す形に変更されている。

Python の変更前後:

変更前:

print(response.content[0].text)

変更後:

# response.content は ContentBlock オブジェクトのリスト
for block in response.content:
    if block.type == "text":
        print(block.text)

Ruby では .type が Symbol であることが明記され（:text と比較する）、TypeScript では ContentBlock[] が判別共用体であり .type で絞り込まないとコンパイルエラーになることがコメントで示された。

その他の修正:

• PHP SDK: BedrockClient / VertexClient / FoundryClient が廃止され、それぞれ Bedrock\Client::fromEnvironment() / Vertex\Client::fromEnvironment() / Foundry\Client::withCredentials() のスタティックファクトリへ変更
• Go SDK: context.TODO() が context.Background() へ統一、ストリームの最終メッセージ集約パターン（message.Accumulate(stream.Current())）が追記
• Java SDK: バージョンが 2.15.0 から 2.16.1 へ更新
• TypeScript ツールループ: pause_turn 時にメッセージ配列を再構築していたコードが、messages.push() で追記する正しい実装に修正
• curl: レスポンスの jq パース方法が追記され、grep/sed によるJSONパースが非推奨として明示された
• コンパクション: Beta, Opus 4.6 only から Beta, Opus 4.6 and Sonnet 4.6 へ対応モデルの記述を更新
• Agent SDK（Python/TypeScript）: dontAsk パーミッションモードの挙動説明を修正（TypeScriptでは「事前承認されていない操作を拒否するモード」と明確化）、allow_dangerously_skip_permissions フィールドの扱いを整理、セッション履歴APIや新規フックイベントを追記

設計判断

静的ドキュメントとライブAPIの役割分担が明確化された。 従来は静的テーブルのみで管理していたモデル能力情報を、「テーブルはキャッシュ」と位置づけ、ランタイムでの確認が必要な場面には Models API を使う設計に整理された。これにより、新モデルリリース時のドキュメント追従遅延の影響を限定的にしている。

max_tokens のデフォルト値については、「低すぎる値は出力の途中打ち切りとリトライを招く」という原則を明示した上で、ストリーミング/非ストリーミングという技術的制約に基づいて異なる値を使い分ける判断が採られている。単一の「安全なデフォルト」ではなく、リクエスト種別ごとに根拠を持たせた値を示している点が特徴的だ。

まとめ

本PRは、コードサンプルの実用性向上（max_tokens の見直しと型安全なコンテンツアクセス）と、モデル能力情報を動的に取得するための新しい参照パターンの提供という、二つの軸でドキュメント品質を引き上げている。スキルドキュメントを参照するエージェントがより堅牢なコードを生成できるよう、サンプル自体を「正しいパターンのリファレンス実装」として整備する方向性が一貫して示されている。