deprecation-and-migration Skill for Claude: Retire Code and Migrate Safely

deprecation-and-migration makes Claude plan how to retire old code or change a live database without breaking the people who depend on it.

Installs: 61.7K; on skills.sh
Stars: 112.6K; on GitHub
Updated: Nov 2026; last repo commit

This skill, from Addy Osmani's agent-skills collection, makes Claude ask five questions before anything is deprecated. Is it still useful, who depends on it, does a replacement exist, what does each user pay to move, and what does keeping it cost. Then it walks through building the replacement, announcing the change, migrating users one at a time and removing the old system only after usage is verified at zero.

It also covers database schema changes with the expand and contract pattern. The SKILL.md works through renaming name to full_name in five deploys, with the rule that drops and renames ship alone, after no code reads the old column. The skill is one SKILL.md file with no bundled scripts.

Good for

Engineers retiring an old API, library or feature
Teams renaming or dropping a column in a production database
Tech leads deciding whether to maintain or sunset a legacy system

Install deprecation-and-migration

Claude Code

Copy this prompt.

Install the deprecation-and-migration skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill deprecation-and-migration

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

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

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Overview
When to Use
Core Principles
Code Is a Liability
Hyrum's Law Makes Removal Hard
Deprecation Planning Starts at Design Time
The Deprecation Decision
Compulsory vs Advisory Deprecation
The Migration Process
Step 1: Build the Replacement
Step 2: Announce and Document
Deprecation Notice: OldService
Migration Guide
Step 3: Migrate Incrementally
Step 4: Remove the Old System
Migration Patterns

Key facts

Author: addyosmani (GitHub repo owner)
Repo: addyosmani/agent-skills
Installs on skills.sh: 61,685 as of 2026-11-02
GitHub stars (repo): 112,555 as of 2026-11-02
Last repo commit: 2026-11-01
License: MIT
Files: 1 file (SKILL.md only)
Works in: Claude Code, Cursor, Codex, Gemini CLI, Antigravity CLI, Windsurf, OpenCode, GitHub Copilot and Kiro (README lists setup for each)
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Five questions to answer before deprecating anything
Does it still give unique value, how many consumers depend on it, does a replacement exist, what does migration cost each consumer, and what does not deprecating cost over time.
The deprecation decision
Choose a nudge or a hard deadline
Advisory means warnings and docs and users move at their own pace. Compulsory means a hard removal date with migration tooling. The skill defaults to advisory.
Advisory vs compulsory
Four steps from replacement to removal
Build the replacement, announce and document, migrate consumers one at a time, then remove the old system once metrics show no active use.
The migration process
Strangler, adapter and feature flag
Strangler routes traffic from old to new in phases. Adapter keeps the old interface on top of the new code. Feature flags switch consumers one at a time.
Migration patterns
Change columns in additive phases
Add the new column, dual-write, backfill in batches, switch reads, then drop the old column in a separate later deploy. Each migration needs a tested down path.
Database schema migrations (expand/contract)
Code nobody owns but everybody uses
The skill's signs: no recent commits, no maintainer, failing tests nobody fixes. The response is to assign an owner or deprecate with a plan.
Zombie code
Checks to finish a deprecation or migration
Two checklists: one for deprecations (replacement proven, consumers migrated, old code and notices removed) and one for schema changes.
Verification checklist

From the official docs

Questions

What does the deprecation-and-migration skill do?

It makes Claude plan removals before acting. Claude checks whether the old system should go, picks advisory or compulsory deprecation, migrates users in steps and verifies zero usage before deleting code. It also covers production database changes with expand and contract.

How do I install deprecation-and-migration?

Use the install box above. The README says npx skills add addyosmani/agent-skills --skill <name> installs a single skill and the plugin route installs the whole collection. The README says a per-skill install copies only skills/<name>/, not the repo-level references/ folder. This SKILL.md does not link to the repo's references/ folder.

Does it work in Cursor, Codex or the Claude app?

The README gives setup for Claude Code, Cursor, Codex, Gemini CLI, Antigravity CLI, Windsurf, OpenCode, GitHub Copilot and Kiro. It does not cover the Claude app, so this page does not claim it.

Does it help with renaming a database column?

Yes. The expand and contract section works through a rename of name to full_name in five steps, each deployable on its own. Adds are safe in any deploy. Drops and renames get their own deploy after no code references the old column.

Does it run any commands or need an API key?

The skill is a single SKILL.md of instructions with no bundled scripts, and its text names no API key. Claude still makes the code and migration changes you approve in your own project.

Is it safe to use?

It is instructions for Claude, with no bundled scripts. They tell Claude to migrate users incrementally, keep a tested down path for every migration and delete old code only after usage checks. Claude still edits your code and writes migrations in your project, so review each change, and give any migration that touches production data your own review before it runs.

Which other skills does it mention?

It points to incremental-implementation for thin vertical slices when you apply each migration phase. That skill lives in the same repo and is optional.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/deprecation-and-migration

addyosmani/agent-skills skills.sh

Sources

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

Show all 2

deprecation-and-migration SKILL.md · github.com
addyosmani/agent-skills README · github.com