agentleFS
Sign inStart free
juandelossantosjuandelossantos/another-agent-skills/skills/deprecation-and-migration/SKILL.md

deprecation-and-migration

Skill1 starsChanged 11 days agoMITView on GitHub

Manage deprecation and migration of old systems, APIs, and features. Covers sunset strategies, backward compatibility, timelines. Do NOT use for new feature development.

We split this skill into the rules it gives an agent

3 rules. 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 54 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every deprecation needs a written notice sent before the change.

    line 80
  2. Distinctive:

    No migration path — removing the old system without telling users what replaces it.

    line 85
  3. Distinctive:

    No rollback plan — the new system has issues and the old system is already gone.

    line 87

“Common” is measured: kept by at least 6 in 10 of the 54 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Deprecation and Migration

Remove old systems safely. Migrate users without breaking trust.

The only skill that covers the full lifecycle of retiring functionality: deciding what to sunset, planning migration paths, maintaining backward compatibility during transition, and communicating changes to users.

Sources: OpenAPI Specification (openapis.org) — deprecation marking, backward compatibility rules, versioning scheme. Semantic Versioning 2.0 (semver.org) — breaking change rules. Strangler Fig pattern (Martin Fowler) — incremental migration. Google SRE Workbook (sre.google/workbook) — sunset procedures.

When to Use

  • Removing or replacing an existing API endpoint
  • Migrating users from one implementation to another
  • Deciding whether to maintain or sunset existing code
  • Planning backward-compatible transitions
  • A third-party API or dependency your system relies on announces deprecation

Output Contract

Deprecation + migration plan — documented timeline (Announce → Deprecate → Support → Sunset) with source code changes in existing source tree, migration strategy chosen with risk level (parallel/strangler/big-bang/phased), backward compatibility rules followed (breaking = MAJOR), deprecated endpoints marked with deprecated flag + Sunset HTTP header, deprecation notice published before support window, migration guide with before/after examples, rollback plan in place, old system officially sunset after window expires.

When NOT to Use

  • Building new features (use feature implementation skills)
  • Deployment (use shipping-and-launch)

Deprecation Lifecycle

Announce → Deprecate → Support Window → Sunset
PhaseDurationWhat Happens
AnnounceBefore deprecation releasePublish changelog, migration guide, deprecation timeline
DeprecateFrom releaseMark feature as deprecated, warn users on access
Support window6-12 monthsOld version still works, users migrate on their schedule
SunsetAfter windowRemove feature, return 410 Gone or redirect to replacement

The support window must be long enough for all known users to migrate. One year is standard for public APIs. Internal systems can use shorter windows (3-6 months).

Migration Strategies

StrategyHow It WorksRiskBest For
Parallel runOld and new systems run simultaneouslyLowCritical systems, gradual cutover
Strangler FigRoute traffic incrementally from old to newMediumLarge monoliths, gradual replacement
Big BangSwitch all traffic at onceHighSimple replacements, feature flags
Phased rolloutMigrate users in groupsMediumMulti-tenant systems

See guides/MIGRATION-STRATEGIES.md for decision trees and detailed implementation patterns.

Backward Compatibility

Additive changes are always backward compatible. Removing or changing behavior requires a deprecation window.

Change TypeCompatible?Version Bump
Adding an optional fieldYesMINOR
Adding a new endpointYesMINOR
Removing a fieldNo — breakingMAJOR
Changing a field typeNo — breakingMAJOR
Adding a required fieldNo — breakingMAJOR
Changing endpoint URLNo — breakingMAJOR

Communication

Every deprecation needs a written notice sent before the change. See guides/DEPRECATION-COMMUNICATION.md for templates covering deprecation notices, migration guides, and sunset announcements.

Anti-Patterns

  1. Silent removal — deleting a feature without warning. Users discover it's gone.
  2. No migration path — removing the old system without telling users what replaces it.
  3. Too short a window — deprecating on Friday and removing on Monday.
  4. No rollback plan — the new system has issues and the old system is already gone.
  5. Deprecation without replacement — removing a feature with no alternative.
  6. Forcing migration — breaking existing users instead of giving them time.

Verification

  • Deprecation lifecycle defined with timeline
  • Migration strategy chosen and documented
  • Backward compatibility rules followed (breaking = MAJOR version)
  • Deprecation notice published before support window starts
  • Migration guide provided with clear before/after examples
  • Rollback plan in place if migration fails
  • Old system officially sunset after window expires

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free