claude-api スキルのモデルデフォルトを Claude Opus 4.7 へ更新、モデル移行ガイドを新設

2026年04月17日 04:12 JST anthropics/skills

https://github.com/anthropics/skills/pull/956

claude-api スキル全体のデフォルトモデルを claude-opus-4-6 から claude-opus-4-7 へ移行すると同時に、Anthropic SDK を使ったコード資産をモデル間で移行するための包括的なガイド shared/model-migration.md が新たに追加された。

背景

claude-opus-4-7 のリリースに伴い、スキル全体のリファレンス実装を最新モデルへ追従させる必要が生じた。今回の更新前は、Python・TypeScript・Go・Ruby・PHP・Java・C#・cURL の全言語ガイドおよび Managed Agents ドキュメント内のサンプルコードが claude-opus-4-6 をハードコードしており、利用者がスキルに従ってコードを書くと旧モデルを参照し続ける状態だった。

加えて、モデルバージョン間の移行作業自体が Claude API スキルのユースケースとして認識されるようになった。SKILL.md のトリガー条件に「既存の Claude API コードをモデルバージョン間で移行する」が追加されており、スキルとして扱うべき用途が明示的に拡張されている。

技術的な変更

モデル ID の一括更新

すべての言語サンプルで claude-opus-4-6 → claude-opus-4-7 への置換が行われた。変更対象は Managed Agents の agents.create() 呼び出し、Messages API の基本例、ストリーミング、ツールユース、バッチ処理、Files API など広範に及ぶ。モデルテーブルにも claude-opus-4-7（コンテキスト 1M トークン）が追加され、claude-opus-4-6 も引き続き 1M トークン対応として併記された。

変更前（例: python/claude-api/README.md）:

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)

変更後:

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)

Opus 4.7 固有の破壊的変更の文書化

shared/error-codes.md に Opus 4.7 特有の 400 エラーが追記された。temperature・top_p・top_k パラメータが Opus 4.7 では削除されており、これらを送信すると 400 が返る。また thinking: {type: "enabled", budget_tokens: N} も削除され、代わりに thinking: {type: "adaptive"} を使う必要がある。shared/models.md の API レスポンスサンプルも更新され、Opus 4.7 では thinking.types.enabled.supported が false になっている点が明示された。

Files API の `scope_id` パラメータ修正

Managed Agents のセッション出力ファイルを取得する際のパラメータが session_id から scope_id に修正された。あわせて、managed-agents-2026-04-01 ベータヘッダーを明示的に渡す必要があることが各言語のサンプルに反映されている。

変更前（python/managed-agents/README.md）:

files = client.beta.files.list(session_id=session.id)

変更後:

files = client.beta.files.list(
    scope_id=session.id,
    betas=["managed-agents-2026-04-01"],
)

@anthropic-ai/sdk ≥ 0.88.0 / anthropic（Python）≥ 0.92.0 以上が必要なことも明記された。

`shared/model-migration.md` の新設（779 行）

最大の変更は 779 行に及ぶ shared/model-migration.md の追加だ。このファイルは以下の構成を持つ:

Step 0: 移行スコープの確認 — ファイル編集前にスコープを必ず確認するよう求める。「my project」「everywhere」などの曖昧な表現はスコープ未定義として扱い、明示的に確認することを非交渉可能なルールとして規定。
Step 1: ファイルの分類 — 各ファイルを swap / add-alongside / skip に分類する手順。
Per-SDK Syntax Reference — Python サンプルを TypeScript・Go・Ruby・Java・C#・PHP へ変換するためのリファレンス。
Destination Models / Retired Model Replacements — 移行先モデルの選定基準。
Breaking Changes by Source Model — Opus 4.6・Sonnet 4.6 への移行時の破壊的変更一覧。
Migrating to Opus 4.7 — Opus 4.7 固有の破壊的変更、サイレントなデフォルト変更、ふるまいの変化を詳述。
Opus 4.7 Migration Checklist — [BLOCKS]（必須）と [TUNE]（任意調整）にタグ付けされたチェックリスト。
Verify the Migration — 編集後のランタイム検証手順。

設計判断

移行スコープ確認を「非交渉可能なルール」として明文化

model-migration.md は移行操作の開始前にスコープ確認を求めることを non-negotiable と明記しており、「migrate my codebase」「upgrade to Sonnet 4.6」のような命令的に聞こえるリクエストですら曖昧スコープとして扱う。これは、スキルが AI エージェントとして動作する際に意図しない大規模ファイル編集を防ぐためのガードレールとして機能する。

Archive の永続性を複数箇所で繰り返し警告

managed-agents-core.md・managed-agents-environments.md・managed-agents-events.md・managed-agents-overview.md の複数箇所に、エージェントおよび環境の archive が永続的（アンアーカイブ不可） であるという警告が追加された。セッションの archive はルーチンなクリーンアップとして許容される一方、エージェント・環境の archive はプロダクション運用上の重大操作として区別されている。

バッファリングを自前で書かずに SDK のストリームヘルパーを優先

managed-agents-overview.md の Common Pitfalls に「HTTP ライブラリのタイムアウトをウォールクロックの上限として信頼しない」という注意が追加された。requests や httpx のタイムアウトがチャンクごとにリセットされる per-chunk read timeout である点を明示し、SDK の sessions.events.stream() を優先するよう誘導している。

カスタムツールによるシークレットのホスト側保持パターン

コンテナ内に環境変数を注入する手段が現時点では存在しないことを明示したうえで、managed-agents-client-patterns.md Pattern 9 として「カスタムツールを経由してシークレットをホスト側に置く」パターンが強化された。agent.custom_tool_use → オーケストレーター側で認証実行 → user.custom_tool_result という SSE ストリーム上でのフローが図示されており、パブリックエンドポイントを公開しないセキュリティ特性も説明に加えられた。

まとめ

この PR は単純なモデル ID の一括置換に留まらず、モデル移行そのものをスキルとして体系化した点に意義がある。Opus 4.7 固有の破壊的変更（temperature / top_p / top_k の削除、budget_tokens の廃止）をエラーコードドキュメントと移行ガイドの両面から文書化することで、スキルを利用するエージェントが旧パラメータを誤って使用するリスクを構造的に低減している。

背景