api-platform-versioning — Claude Code skill: what it does
api-platform-versioning keeps API Platform clients alive through renames and removals: deprecation with a sunset date first, parallel versions as the last resort.
MIT ★ 234 updated 2026-10-05
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-codeWhat api-platform-versioning does
Claude gets a fixed order of operations for a breaking change in API Platform. Start with deprecation. Set deprecationReason on the resource, the operation, or an #[ApiProperty]. Then add sunset: with a date, and on v4 a headers block carrying Deprecation (RFC 9745) and a Link with rel="successor-version". On earlier releases a KernelEvents::RESPONSE listener emits those headers.
Parallel surfaces are the fallback. /v1 and /v2 come from separate uriTemplate values with their own groups, or from output DTOs with one provider per version. The old operation is flagged deprecated in OpenAPI, per-version notes are written, and tests run against every version still switched on.
The headers option belongs to v4 and is absent on v3, so check what your project runs. The skill also caps you at 2 or 3 live versions and pushes small additive changes into groups rather than a new version. Deeper implementation notes live in reference.md; allowed tools cover file reads, search, edits and Bash.
What it helps with
- mark a field deprecated without breaking existing clients
- publish a removal date through the
Sunsetheader - run
/v1and/v2of one endpoint side by side - document per-version changes in OpenAPI
- keep tests passing on every live version
Example prompts for the agent
- Mark
legacyPriceas deprecated with a sunset date, usingdeprecationReasonandsunset. - We need
/v2next to/v1— lay out the separateuriTemplateand groups approach. - Check that our API Platform version actually sends the
DeprecationandLinkheaders.
How to install api-platform-versioning
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code2Manually: put the files in place
~/.claude/skills/api-platform-versioning/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/api-platform-versioning/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a codex2Manually: put the files in place
.agents/skills/api-platform-versioning/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a cursor2Manually: put the files in place
.cursor/skills/api-platform-versioning/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dev-toolings/superpowers-symfony content/skills/api-platform-versioning2Manually: put the files in place
.github/skills/api-platform-versioning/SKILL.md1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a gemini-cli2Platform CLI
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/api-platform-versioningManually: put the files in place
.devin/skills/api-platform-versioning/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about api-platform-versioning
How do I install api-platform-versioning in Claude Code?
Run npx skills add dev-toolings/superpowers-symfony --skill api-platform-versioning -a claude-code. The skill lands in ~/.claude/skills/api-platform-versioning/SKILL.md.
What does api-platform-versioning do?
It walks Claude through evolving an API Platform API: deprecation with a sunset date and a successor link, then parallel versions when a breaking representation change cannot be expressed otherwise.
When should I use path versioning instead of deprecation?
Only when deprecation and groups cannot carry the change. The skill treats /v1 and /v2 as the fallback and keeps at most 2 or 3 versions active.
Source text
SKILL.md · MIT
--- name: api-platform-versioning description: Evolve API Platform APIs via deprecation (deprecationReason/sunset, RFC 8594/9745), the recommended alternative to versioning; plus path/header strategies capabilities: [read, search, edit, shell] tags: [api-platform] # projected by `bun run build` — do not edit by hand allowed-tools: - Read - Glob - Grep - Write - Edit - Bash --- # Api Platform Versioning (Symfony) ## Use when - A field, operation, or resource is being renamed or removed and consumers need time to migrate. - Announcing a removal date to clients with `Sunset` and `Deprecation` headers. - Deciding between deprecation and parallel `/v1` and `/v2` surfaces. - A breaking representation change that deprecation and groups cannot express. ## Default workflow 1. Try deprecation first: set `deprecationReason` on the resource, the operation, or `#[ApiProperty]`. 2. Add `sunset:` with a date, and on v4 add `headers` carrying `Deprecation` (RFC 9745) and a `Link` with `rel="successor-version"`. 3. Before v4, emit those headers from a `KernelEvents::RESPONSE` listener. 4. Only if still breaking, expose parallel `uriTemplate` values (`/v1`, `/v2`) with distinct groups, or output DTOs with one provider per version. 5. Mark the old operation as deprecated in OpenAPI, document the changes per version, and test every active version. ## Guardrails - Prefer deprecation: path versioning is the fallback, not the default. - Always set a sunset date and keep at most 2 or 3 versions active. - `deprecationReason` and `sunset` are stable across v3 and v4, but the RFC 9745 `headers` option is v4-era: verify it on your installed version. - Use groups for minor additive changes rather than a new version. ## Progressive disclosure - Use this file for execution posture and risk controls. - Open references when deep implementation details are needed. ## Output contract - The deprecation or versioning strategy chosen and why. - Deprecated elements with their sunset dates and successor links. - Tests for each active version and for the headers. ## References - `reference.md`
© dev-toolings · MIT · dev-toolings/superpowers-symfony