deprecation-and-migrationcommit 9f91cc4SKILL.md · Architecture Tuning
Deprecation and Migration
Guides removing old systems, APIs or features, moving consumers safely to a replacement, and changing database schemas via expand/contract.
npx skills add addyosmani/agent-skills --skill deprecation-and-migrationCommand selected. Copy it manually.
- Permissions
- read-repo
- write-files
- shell
- network
- Compatible with
- Claude Code, Codex, Cursor, Copilot, Gemini CLI
- GitHub
- 112.3k
- Source
- Community · Addy Osmani
- Status
- Scan passed
- License
- MIT
- Category
- Architecture Tuning
Core rule
Never deprecate without a working replacement, and never change a database column in place.
Execution Phases
Phase 01Decide on deprecation
Weigh remaining unique value, number of consumers, migration cost and the cost of not deprecating; default to advisory deprecation.
Phase 02Build the replacement
The replacement must cover critical use cases, ship with docs and a migration guide, and be proven in production before announcing.
Phase 03Migrate incrementally
Move consumers one at a time using strangler, adapter or feature-flag patterns; run schema changes as expand, backfill, contract.
Phase 04Remove the old system
After metrics and logs show zero active usage, remove the old code, tests, docs, configuration and deprecation notices.
Permissions (summarised from SKILL.md)
| Capability | Needed | Details |
|---|---|---|
| File writes | Required | Writes replacement code, adapters, migrations and deprecation notices, and deletes old code with its tests and docs. |
| Command execution | Required | Runs tests and integration checks to verify behavior, and runs each migration's down path before merging. |
| Network outbound | Not required | The skill does not call external networks or services. |
SKILL.md frontmatter (YAML)
---
name: deprecation-and-migration
description: Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.
---