Guide · Agent skill
How to use the Deprecation and Migration agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The deprecation-and-migration skill gives an AI agent a structured process for removing old systems, APIs and features, and for moving users from an old implementation to a new one. It also covers zero-downtime database schema changes using the expand/contract method. This guide explains what the skill does, how to install it, how to ask for it with natural requests, and what to check before you rely on its output.
Deprecation and Migration Guideaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Get the ZIP for skills/deprecation-and-migration from the directory page and unzip it. It contains SKILL.md.
- 2Place it where your agent can read it. Put the folder in ~/.claude/skills/ for personal use, or in your project's .claude/skills/ folder. Alternatively, upload it in the Claude apps under Settings, then Capabilities, then Skills.
- 3Describe your task in plain language. Name the system you are retiring or changing and your goal, such as sunsetting an API or renaming a column without downtime.
- 4Review the plan the agent produces. Check the decision questions, consumer list and migration order against what you know about your users and data.
- 5Migrate in small, reviewed steps. Apply changes one consumer or one schema phase at a time, verifying behaviour before moving on.
- 6Remove the old system last. Only remove code or columns after confirming zero active usage through metrics, logs or dependency analysis.
What the skill makes the agent do
Once the skill is loaded, the agent follows a set process for retiring code. It helps you decide whether code still earns its keep, choose between advisory and compulsory deprecation, write a deprecation notice, and migrate users incrementally. The skill names patterns for this work, including strangler, adapter and feature flag migration.
The skill also covers changing a live database schema without downtime, such as renaming or dropping a column. In that case it uses expand/contract: add the new structure first, migrate data, then remove the old structure in a later release.
The skill is written as guidance and example code. It does not change your project on its own.
- Decide whether to maintain or sunset a system
- Choose advisory or compulsory deprecation
- Write deprecation notices and migration guides
- Migrate consumers one at a time using strangler, adapter or feature flag patterns
- Rename or drop database columns with expand/contract
Install the skill from the ZIP or the Claude apps
Download the ZIP for skills/deprecation-and-migration from the directory page and unzip it. The package contains one file, SKILL.md. For a personal setup, place the unzipped skill in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.
- Personal install: ~/.claude/skills/
- Project install: the .claude/skills/ folder inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
You do not need a special command. The skill's description lists the situations it applies to, so describe your task in plain language and mention the deprecation or migration goal. Include the system, the number of users or consumers if you know them, and whether you need a plan, a notice, or a schema change.
Requests that match the skill's described uses include removing an old API, moving users from one implementation to another, renaming a production column without downtime, and deciding whether to keep maintaining a legacy component.
- Help me plan sunsetting the v1 payments API. Which consumers do I need to migrate first?
- Write a deprecation notice for our legacy reporting module and a migration guide for users.
- Plan a zero-downtime rename of the name column to full_name using expand/contract.
- Should we keep maintaining the old job scheduler or migrate off it?
Example: the expand/contract process for a column rename
The skill's worked example renames a column called name to full_name. The steps are designed so that old and new code both work at every stage, which avoids a window where one version queries a column that no longer exists.
The skill's sequence is: add full_name as nullable; deploy the app so it writes both columns; backfill existing rows in batches to avoid locking the table; switch reads to full_name; and only after no code reads the old column, drop it in a separate, later deploy.
- Expand: add the new column, nullable, alongside the old one
- Dual-write: the app writes both columns
- Backfill: copy existing rows in batches
- Switch reads, then contract: drop the old column in a later deploy
EXPAND ──────────────→ MIGRATE ──────────────→ CONTRACT
add the new column, backfill existing rows, once no code reads the
nullable, alongside dual-write old+new from old column, drop it in
the old one the app a later, separate deployUse the deprecation notice and migration patterns
The skill includes a deprecation notice template with a status, replacement, removal plan, reason and migration steps. Its example notice says the old service is advisory with no hard deadline yet, which reflects the default the skill recommends.
For the code side, the skill shows an adapter that keeps the old interface while calling the new implementation, and a feature flag pattern that chooses the new or old service per user. Treat these as starting points to adapt to your codebase.
- Default to advisory deprecation; use compulsory only when maintenance cost or risk justifies it
- Compulsory deprecation requires migration tooling, documentation and support
- Verify zero active usage before removing code
What you need and safety notes
The skill lists no requirements. It does not run scripts and does not use the network. Its output is advice and templates, so you still need your own tools and tests to carry out any change.
Review every migration before it touches production data. The skill is not meant to run migrations automatically. The command in the example notice, npx migrate-check, is a placeholder inside a sample document, not a tool that ships with this skill.
- Requirements: none listed
- Runs scripts: no
- Uses network: no
- Do not execute production data changes without review
What people use it for
- Planning the sunset of a legacy API while keeping existing consumers working
- Writing a deprecation notice and migration guide for an internal library
- Renaming or dropping a production database column with expand/contract
- Deciding whether a legacy service is worth maintaining or should be migrated off
Frequently asked questions
How do I install the deprecation and migration agent skill?
Download the ZIP for skills/deprecation-and-migration from the directory page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings, then Capabilities, then Skills.
Is the deprecation and migration skill free to use?
The skill is published under the MIT licence, as listed on its directory page. The source does not mention pricing for the Claude apps or any other service you use with it.
Does the skill need any other software or setup?
The skill lists no requirements. It does not run scripts and does not use the network, so it adds guidance to your agent without installing tools.
Will the agent run database migrations for me automatically?
No. The skill provides advice, checklists and example code, and it does not change your project by itself. Review any migration before running it against production data.
When should I use this skill instead of just deleting old code?
Use it when the old code has users or consumers who need a path to the replacement. For simple one-off deletions with no users, the skill's process is more than you need.
My agent does not seem to use the skill. What should I check?
Confirm that the folder containing SKILL.md is in ~/.claude/skills/ or the project's .claude/skills/ folder, or that you uploaded it under Settings, then Capabilities, then Skills. Then describe a task that matches its uses, such as removing an old API or renaming a production column.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are planning to sunset a legacy API, library or feature, or if you need to change a production database column without downtime and want a disciplined checklist. Pick something else if you only need to delete unused code with no consumers, want the agent to execute migrations unattended, or are looking for a general project-management template.
Download the skill