# Deprecation and Migration (deprecation-and-migration)

> Guides removing old systems, APIs or features, moving consumers safely to a replacement, and changing database schemas via expand/contract.

- Category: [Architecture Tuning](https://www.myskills.tools/en/categories/architecture-tuning/)
- Source: Community · Addy Osmani
- Repository: https://github.com/addyosmani/agent-skills/tree/main/skills/deprecation-and-migration (commit 9f91cc4)
- SKILL.md: https://github.com/addyosmani/agent-skills/blob/main/skills/deprecation-and-migration/SKILL.md
- Install command: `npx skills add addyosmani/agent-skills --skill deprecation-and-migration`
- License: MIT
- Compatible with: Claude Code, Codex, Cursor, Copilot, Gemini CLI
- Permissions: read-repo ✓, write-files ✓, shell ✓, network ✗
- Status: Scan passed
- A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.

## Core rule

Never deprecate without a working replacement, and never change a database column in place.

## Execution Phases

1. **Decide on deprecation** — Weigh remaining unique value, number of consumers, migration cost and the cost of not deprecating; default to advisory deprecation.
2. **Build the replacement** — The replacement must cover critical use cases, ship with docs and a migration guide, and be proven in production before announcing.
3. **Migrate incrementally** — Move consumers one at a time using strangler, adapter or feature-flag patterns; run schema changes as expand, backfill, contract.
4. **Remove 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)

```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.
---
```

Home: https://www.myskills.tools/en/ · URL: https://www.myskills.tools/en/skills/deprecation-and-migration/