Deprecation and migration skill for Claude Code: what it does and how to install it

Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026

What is the deprecation and migration skill?

The deprecation and migration skill teaches Claude Code and other coding agents how to remove old code safely: decide whether something should go, move every consumer to a replacement, and only then delete it. It also covers the riskiest kind of migration, a production database schema change, with a step-by-step expand/contract plan.

It is one of 25 skills in addyosmani/agent-skills, which the README describes as "Production-grade engineering skills for AI coding agents." The skill's description reads: "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."

As of 24 October 2026, its skills.sh page listed 56.1K installs (snapshot, 24 October 2026).

What does it do?

The skill is a single SKILL.md with no scripts or reference files. Its starting point is blunt: "Code is a liability, not an asset." From there it gives the agent a decision process and a set of migration patterns.

When it triggers. The SKILL.md lists these situations: replacing an old system, API or library; sunsetting a feature; consolidating duplicate implementations; removing dead code that nobody owns; planning the lifecycle of a new system; and deciding whether to keep a legacy system or invest in migration.

The deprecation decision. Before removing anything, the agent works through five questions: does the system still provide unique value, how many consumers depend on it, does a replacement exist, what each consumer's migration costs, and what keeping it costs. If no replacement exists, the skill says to build one first.

Advisory or compulsory. Advisory deprecation uses warnings and docs and lets users move when they are ready. Compulsory deprecation sets a removal date and requires tooling and support. The rule is "Default to advisory."

A four-step migration process. Build the replacement, announce and document it (the skill includes a template deprecation notice), migrate consumers one at a time, then remove the old system only after usage reaches zero. It adds what it calls the Churn Rule: if you own the infrastructure being deprecated, you migrate your users or ship backward-compatible updates.

Migration patterns. Three code patterns are spelled out, with TypeScript examples for two of them:

Expand/contract schema migrations. This section is the most practical. Its worked example renames name to full_name in five steps: add the new column as nullable, dual-write both columns, backfill in batches, switch reads, then stop writing name and drop it in a separate later deploy. The rules that go with it: additive changes first and destructive ones last and alone, a tested down path for every migration, batched backfills off the hot path, and non-blocking index builds such as Postgres CREATE INDEX CONCURRENTLY.

It closes with a section on zombie code (code nobody owns but everybody depends on), a table of common rationalizations with rebuttals, red flags, and two verification checklists, one for deprecations and one for schema migrations.

How do you install it?

The skills.sh page gives this command for just this skill:

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

The skills CLI installs the folder into your project's .claude/skills/deprecation-and-migration/, or into ~/.claude/skills/deprecation-and-migration/ for every project, which are the standard Claude Code skill locations. The README notes that a per-skill install copies only the skill folder, not the repo-level references/ directory. This skill does not point to any shared checklist there, so nothing is lost.

Whole pack as a Claude Code plugin. From the README:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

That also installs the repo's slash commands (/spec, /plan, /build, /test, /review, /ship and others) and the other 24 skills. Plugin skills are namespaced as /plugin-name:skill-name in Claude Code.

claude.ai. You can zip the deprecation-and-migration folder and upload it under Customize > Skills, as described in Anthropic's help article on skills. The MIT License allows this.

Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

How do you use it?

The skill is model-invoked, so the agent can load it when you mention removing, replacing or migrating something. In Claude Code you can also type /deprecation-and-migration.

Example prompts (suggestions, not quotes from the repo):

• We're replacing the v1 /orders endpoint with v2. Write a deprecation notice and a migration plan for our three internal consumers.
• Rename users.name to users.full_name in production without downtime. Plan the deploys using expand/contract.
• This legacy PDF export module has no owner. Should we keep it or deprecate it? Work through the decision questions.
• Put the new payment client behind a feature flag so we can move tenants over one at a time.
• Check this migration PR against the schema migration checklist before I merge it.

There are no packages, credentials or scripts. You need your project's own migration tool and, for the data steps, a way to measure usage (logs or metrics), because the skill asks the agent to confirm zero active consumers before deleting anything.

Tips and limits

• It plans; your tools execute. The skill gives the order of deploys and the checks between them. It does not generate ORM-specific migration files, so pair it with your migration tool's docs.
• Expect more deploys than you planned. Expand/contract turns one rename into several separate deploys plus a batched backfill. That is the point, but tell the agent if your release process makes that costly so it can group steps sensibly.
• "Remove" means remove. Step 4 deletes code, tests, docs, config and the deprecation notices. Review those diffs, especially when the agent decides usage is zero from limited evidence.
• Some examples are illustrative. The deprecation notice template mentions npx migrate-check and an old-service package; these are placeholders, not real tools.
• Security audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk.

The skill runs no scripts and writes no files on its own. Under the MIT License you can copy and edit it as long as you keep the copyright notice.

Save it in your Kipt library

Kipt keeps your prompts and skills as Markdown in a private GitHub repo you own. Open Skills and paste the folder link, https://github.com/addyosmani/agent-skills/tree/main/skills/deprecation-and-migration, into the import box. If you paste the repo link instead, it shows a list of its skills so you can also take api-and-interface-design. Everything in your library installs into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Addy Osmani or addyosmani/agent-skills.

Similar skills

• API design skill: Addy Osmani's skill for contract-first interfaces and additive-only changes, which make later deprecations easier.
• Postgres best practices skill: Supabase's rules for indexes, locking and schema design, useful next to the expand/contract steps.
• Improve codebase architecture skill: Matt Pocock's skill for finding refactors that deepen modules before you replace them.
• Security and hardening skill: another skill from the same repo, for the security debt that zombie code collects.