openrouter-upgrade-migration

Openrouter Upgrade Migration

Overview

This skill provides a step-by-step migration guide for upgrading SDK versions, switching between models, or migrating from direct provider APIs to OpenRouter.

Prerequisites

• Existing OpenRouter integration or direct provider API integration
• Test environment for validating the migration

Instructions

1. Audit current integration: Document all API calls, models used, parameters set, and any provider-specific features relied upon
2. Identify breaking changes: If upgrading the SDK, check the changelog for breaking changes; if switching models, compare parameter support and response format differences
3. Update in a feature branch: Make all changes in a branch; update base URL, API key, model IDs, and any changed parameters; add the OpenRouter-specific headers
4. Run comparison tests: Send the same prompts through old and new configurations; compare response quality, latency, and costs to validate the migration
5. Deploy with a rollback plan: Use feature flags or traffic splitting to gradually migrate traffic; keep the old configuration available for quick rollback

Output

• Migration checklist with all changes documented
• Comparison report showing quality, latency, and cost differences
• Rollback runbook in case the migration needs to be reverted

Error Handling

Error	Cause	Fix
Changed response format	New model or SDK version returns different structure	Update response parsing code; add version-specific handling
Missing parameter support	New model doesn't support a parameter used in old code	Remove or conditionally set the unsupported parameter; check /models for capabilities
Quality regression	New model performs worse on specific prompts	Adjust prompts for the new model; consider keeping the old model for affected use cases

See ${CLAUDE_SKILL_DIR}/references/errors.md for full error reference.

Examples

See ${CLAUDE_SKILL_DIR}/references/examples.md for runnable code samples.

Resources

• OpenRouter Documentation
• OpenRouter Models
• OpenRouter API Reference
• OpenRouter Status