PlugWiki

api-versioning-policy Skill (samber): API Versioning and Deprecation

Makes Claude write the versioning and deprecation policy for your API, from what counts as breaking to how a version is retired.

Installs
9.4K
on skills.sh
Stars
9
on GitHub
Files
4
besides SKILL.md
Updated
Nov 2026
last repo commit

api-versioning-policy makes Claude define an API's versioning and deprecation policy. It covers the version scheme, a written breaking-change definition, notice windows by audience, sunset signals such as the Deprecation and Sunset headers, enforcement at the sunset date and governance.

It starts when you mention API versioning, /v2, breaking changes, deprecation, sunset dates or migration windows. Claude asks 8 interview questions, one per message, offers 2 to 3 candidate policies, then drafts and checks the chosen one with you. The skill bundles no scripts.

Good for

  • API teams with a breaking change queued and no written policy
  • Platform leads retiring /v1 and planning the sunset
  • Teams deciding whether GraphQL needs versions at all

Install api-versioning-policy

Claude Code

  1. 1

    Copy this prompt.

    Install the api-versioning-policy skill in Claude Code. Run this command:

/plugin marketplace add samber/developer-platform-skills
/plugin install developer-platform-skills@developer-platform-skills

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The README asks you to install the whole set, not just api-versioning-policy, because the skills reference each other and a lone skill leaves those hand-offs with nowhere to go. The plugin adds all 61 skills in the repo (counted from the repo tree). Its manifests list no hooks, agents or MCP servers.

From the project README. Source.

What's in the skill

When it loads

Define the versioning and deprecation policy for an API - version scheme choice (URI path, header, date-based account-pinned, or deliberate no-versioning), a written breaking-change definition, deprecation notice windows by audience, sunset communication (RFC 9745 Deprecation and RFC 8594 Sunset headers), enforcement at the sunset date (fall-forward vs hard cutoff), and breaking-change governance, with REST version-and-sunset and GraphQL continuous schema evolution treated as separate policies. Use whenever the user mentions API versioning, /v2, breaking changes, deprecation, sunset dates, or migration windows - even if they never say "versioning policy". Client SDK versioning is plain SemVer and belongs to samber/developer-platform-skills@sdk-portfolio-strategy.

Sections in SKILL.md

  1. Interview
  2. Audience split: internal / partner / public
  3. Workflow
  4. 1. Settle the paradigm
  5. 2. Write the breaking-change definition
  6. 3. Choose the version scheme
  7. 4. Set the notice windows and concurrent-version count
  8. 5. Design the sunset communication
  9. 6. Choose the enforcement style at the sunset date
  10. 7. Stand up governance proportionate to blast radius
  11. 8. Brainstorm candidates, then draft and validate the policy
  12. Failure modes
  13. Measurement
  14. Invocation examples
  15. References

Key facts

Author
Samuel Berthe
License
MIT
Version
1.0.3
Installs on skills.sh
9,374 (Nov 2, 2026)
GitHub stars
9 (Nov 2, 2026)
skills.sh audits
Gen Agent Trust Hub pass; Socket pass; Snyk pass (Nov 2, 2026)
Last repo commit
Nov 1, 2026
What installs
5 files including SKILL.md: evals/evals.json and 3 reference files. It bundles no scripts.
Needs
The other skills in the repo; the README says to install the whole set
Works in
Claude Code, Claude.ai, Codex, Cursor, Gemini CLI, and other agents through the skills CLI

What it includes

  • Asks 8 interview questions, one per message, before proposing anything.

    Try: “Write a versioning and deprecation policy for our public REST API - we've never had one and a breaking change is queued.”

    Opening questions

  • Treats REST as version-and-sunset and GraphQL as continuous evolution.

    Settle the paradigm

  • Writes down what counts as breaking and what does not.

    Write the breaking-change definition

  • Ranks five schemes; URI major version is the default rung.

    Choose the version scheme

  • Sets notice by audience, at least 12 months for a fully public API.

    Set notice windows and concurrent versions

  • Stages deprecation as announce, deprecate, sunset and removal, with headers.

    Design the sunset communication

  • Recommends a hard cutoff that returns a clear error as the default.

    Choose the enforcement style

  • Scales review from a CI diff check plus sign-off up to heavier stages.

    Stand up governance

  • Offers 2 to 3 candidate policies, then drafts and checks the chosen one with you.

    Brainstorm, draft and validate the policy

  • Advises saving decisions to developer-platform-context.md when memory is a file.

    Write · Remember decisions (optional)

From the official docs

Permissions

Low risk

This skill is written advice that bundles no scripts. The one thing it may write is a decisions file, so check what Claude saves.

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • It may save decisions to a file

    SKILL.md advises using developer-platform-context.md when memory lives in a file, and calls it an advisory reference. Check or delete that file if you do not want decisions kept. github.com

  • The plugin route adds all 61 skills

    The README asks you to install every skill in the repo, and the repo has 61. The plugin manifests list no hooks, agents or MCP servers, and the repo tree holds none. github.com

  • Folder holds Markdown and one JSON file

    This skill's folder has 5 files: SKILL.md, evals/evals.json and 3 reference files. It has no .py, .sh or .js file. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details
Turning on read-onlyNo read-only setting is documented. Decline the memory-file suggestion if you want no files written.
Scopes

  • Asks you opening questions and works from your answers and anything you share, such as specs or docs

  • May save settled decisions to a file named developer-platform-context.md if your memory lives in a file

Questions

How do I install api-versioning-policy?

Use the install box above. The README asks you to install all 61 skills in the repo, not just this one, because the skills point to each other. In Claude Code that is the plugin route, and elsewhere the skills CLI or the client's own route installs the set.

Does api-versioning-policy work in Claude.ai, Codex or Cursor?

The README documents installs for Claude.ai, Claude Code, Codex, Cursor and Gemini CLI. It also lists the skills CLI, which it calls universal for Agent Skills-compatible tools. The Claude.ai route adds the whole repo as a plugin marketplace.

Does it need an API key or any setup?

SKILL.md sets no environment variable and the folder bundles no scripts. It does ask for details of your own API or product in its opening questions.

Is api-versioning-policy safe to use?

The folder holds Markdown and one JSON file, and no scripts. SKILL.md does suggest saving settled decisions to developer-platform-context.md when your memory lives in a file, so check what Claude writes. Our advice: treat the design it produces as a draft for your team to review before you publish it.

api-versioning-policy vs sdk-portfolio-strategy?

This skill covers API versions and deprecation. SKILL.md says client SDK versioning is plain SemVer and belongs to sdk-portfolio-strategy.

How much notice does it recommend before removing a version?

For a fully public API, at least 12 months, which SKILL.md describes as the floor Google Cloud and Shopify converge on. The skill sets the actual numbers from your audience, and it checks them against a bundled benchmark file.

Information

updated Nov 2, 2026

Repository
samber/developer-platform-skills
Folder
skills/api-versioning-policy

samber/developer-platform-skillsskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6
  1. README · github.com
  2. api-versioning-policy SKILL.md · github.com
  3. api-versioning-policy folder · github.com
  4. sdk-portfolio-strategy SKILL.md · github.com
  5. marketplace.json · github.com
  6. plugin.json · github.com

Updated Nov 2, 2026.