API Deprecation Planner
Plan the retirement of an API endpoint, field, event, tool, or version without surprising active consumers. Use when replacing an interface, removing legacy behavior, publishing a sunset, migrating internal or external clients, or deciding whether observed traffic is safe to turn off.
npx agentscamp add skills/api-deprecation-plannerInstall to ~/.claude/skills/api-deprecation-planner/SKILL.md
Plans API retirement from a verified consumer inventory through replacement parity, announcements, telemetry, migration support, compatibility gates, sunset criteria, shutdown, and cleanup. It treats zero recent traffic as evidence to investigate—not proof that unobserved or infrequent clients do not exist.
Retire an interface through measured migration, not a deletion date alone.
Workflow
- Define the retiring surface. Identify endpoints, methods, fields, event versions, SDK methods, agent tools, error codes, authentication modes, and undocumented behaviors consumers may rely on.
- Inventory consumers. Combine gateway logs, client identifiers, tracing, repository search, SDK telemetry, support records, partner contracts, and owner interviews. State blind spots and the observation window.
- Verify the replacement. Map every required behavior, performance property, permission, error, and operational dependency to the replacement. Record gaps and migration prerequisites.
- Set policy and timeline. Apply versioning commitments, contractual notice, client release cadence, and rare usage cycles. Define announcement, warning, migration, freeze, disablement, and deletion milestones with owners.
- Make deprecation observable. Add safe usage metrics, per-consumer attribution where allowed, structured warnings, response headers or schema directives, dashboards, and alerts for unexpected traffic changes.
- Support migration. Provide side-by-side examples, SDK or codemod support, test environments, compatibility checks, and escalation paths. Avoid telling consumers only that the old interface will disappear.
- Define exit criteria. Require replacement parity, acknowledged high-risk consumers, traffic below a justified threshold for a representative window, passing contract tests, rollback readiness, and accountable approval.
- Disable reversibly before deletion. Prefer a controlled reject, feature flag, route switch, or scoped block with monitoring. Observe the result before removing code, data, documentation, and operational dependencies.
WARNING
Telemetry cannot prove absence when client identification, regions, long-running jobs, or rare workflows are missing. Document the coverage boundary before interpreting zero traffic.
Output
Produce a consumer matrix, replacement gap analysis, milestone timeline, communication plan, telemetry design, migration aids, exit checklist, reversible shutdown procedure, rollback trigger, and final cleanup list.
Frequently asked questions
- How long should an API deprecation window be?
- Set it from the published compatibility policy, consumer release cadence, contract obligations, and the slowest legitimate usage cycle. A monthly or quarterly client cannot be judged from one quiet week.
- Is zero traffic enough to delete an endpoint?
- Not by itself. Confirm telemetry coverage, long-tail schedules, disabled clients, alternate regions, cached clients, and contractual support. Then use explicit owner sign-off and a reversible disablement stage.
Related
- 9 Best Claude Skills for Release ManagementUse Claude skills for readiness reviews, canaries, rollbacks, API deprecations, migrations, versioning, changelogs, and release notes.
- OpenAPI Doc WriterProduce and maintain OpenAPI documentation for an HTTP API. Use when documenting endpoints, request/response schemas, or generating API reference docs.
- SemVer AdvisorDecide the correct semantic-version bump — major, minor, or patch — by diffing a release range, mapping the changes onto the public API surface, and classifying each as breaking, additive, or a fix. Use before cutting a release when you are unsure whether changes are breaking, when a teammate proposes a bump you want to sanity-check, or when a behavior change has no signature change and you need to know if it is still breaking.
- Strangler Fig MigratorPlan the incremental replacement of a legacy module or service using the strangler-fig pattern — grow new code around the old behind an interception seam until the old is dead, instead of a big-bang rewrite. Use when a legacy system is too risky to rewrite at once, or when migrating off a deprecated framework/dependency gradually while staying shippable and rollback-able at every step.
- Changelog From PRsDraft a release changelog by summarizing merged pull requests since the last tag. Use when preparing a release or writing release notes.
- Contract Test DesignerDesign consumer-driven contract tests between services so an API provider can't break its consumers unnoticed — without slow, flaky full end-to-end environments. Use when independent services or teams integrate over an API, when integration bugs only surface in staging or prod, or when E2E suites are too slow and brittle to catch breaking API changes.