API Versioning Skill for OpenAPI Compatibility in Claude Code

Maintain two API versions with explicit contracts, shared business logic, and response adapters for existing clients.

Install in Claude Code

Use a local API, an older response fixture, two OpenAPI documents, and the project's test runner. The example uses path-based versions.

Get the complete `plugins/api-development/api-versioning-manager/skills/versioning-apis` directory from the pinned GitHub commit.
Copy it into the target project's `.claude/skills/`. Check `.claude/skills/versioning-apis/SKILL.md`, start Claude Code at the project root, and call `/versioning-apis`.

Example task

For item 7, make /v1/items/7 return amount: 1000 and /v2/items/7 return price: {amount: 1000, currency: 'CNY'}. Validate both shapes with their own contract tests.

What to check

The v1 client still reads numeric amount. The v2 contract documents the currency. Removing amount from v1 fails its regression test.

Original SKILL.md on GitHub · Updated 2026-11-13

Frequently asked question

Will an OpenAPI diff find a semantic change when the field type stays the same?

Add a behavior assertion for business meaning, such as the amount's units and rounding on representative inputs.