claude-code - 💡(How to fix) Fix [DOCS] `/claude-api` docs omit Opus 4.8 migration guidance

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/commands

Section/Topic

/claude-api [migrate|managed-agents-onboard] command entry

Current Documentation

The commands reference currently describes /claude-api migrate generically:

Skill. Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports anthropic or @anthropic-ai/sdk. Run /claude-api migrate to upgrade existing Claude API code to a newer model: Claude asks which files to scan and which model to target, then updates model IDs, thinking configuration, and other parameters that changed between versions.

The model configuration page documents Opus 4.8 availability and some behavior differences separately:

On the Anthropic API, opus resolves to Opus 4.8 and sonnet resolves to Sonnet 4.6.

Opus 4.8 requires Claude Code v2.1.154 or later. Run claude update to upgrade.

The default effort is high on Opus 4.8, Opus 4.6, and Sonnet 4.6, and xhigh on Opus 4.7.

What's Wrong or Missing?

Claude Code v2.1.154 added Claude Opus 4.8 support and 4.7 to 4.8 migration guidance to the /claude-api skill, but the user-facing /claude-api documentation does not mention that new specific coverage.

The current docs tell users that /claude-api migrate can update model IDs, thinking configuration, and other changed parameters, but they do not say that the skill now knows about the Opus 4.7 to Opus 4.8 migration path. Users deciding whether to run the skill for an Opus 4.8 upgrade have to infer that from separate model-configuration content and the changelog rather than from the /claude-api command documentation.

This is a distinct gap from the general Opus 4.8 model docs: the model page documents availability and effort defaults, while the /claude-api entry should make the migration-skill capability discoverable at the point where users learn what the skill does.

Suggested Improvement

Update the /claude-api command entry to mention Opus 4.8 migration support explicitly.

Suggested minimum addition:

For Opus upgrades, /claude-api migrate includes guidance for moving Claude API code from Opus 4.7 to Opus 4.8, including model ID changes, effort/default behavior, thinking configuration, and provider-specific model ID formats where applicable.

If a dedicated /claude-api skill page is intended to exist, add the same Opus 4.8 migration coverage there and link to it from the command entry.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 Claude Code pages affected

Version context: Claude Code v2.1.154 changelog entry: "Added Claude Opus 4.8 support and 4.7 -> 4.8 migration guidance to the /claude-api skill".