Manages deprecation and migration. Use when removing old systems, APIs, features, or skills. Use when migrating consumers from one implementation to another. Use when deciding whether to maintain or sunset existing code.
Code is a liability, not an asset. Every line has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep. Migration is the process of moving consumers safely from old to new.
Most teams are good at building things. Few are good at removing them. This skill addresses that gap.
The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement.
When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate.
Before deprecating anything, answer these questions:
1. Does this system still provide unique value?
→ If yes, maintain it. If no, proceed.
2. How many consumers depend on it?
→ Quantify the migration scope.
3. Does a replacement exist?
→ If no, build the replacement first. Don't deprecate without an alternative.
4. What's the migration cost for each consumer?
→ If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
5. What's the ongoing maintenance cost of NOT deprecating?
→ Security risk, engineer time, opportunity cost of complexity.
| Type | When to Use | Mechanism |
|---|---|---|
| Advisory | Migration is optional, old system is stable | Warnings, documentation, nudges. Consumers migrate on their own timeline. |
| Compulsory | Old system has security issues, blocks progress, or maintenance cost is unsustainable | Hard deadline. Old system removed by date X. Provide migration tooling. |
Default to advisory. Compulsory deprecation requires providing migration tooling, documentation, and support.
Don't deprecate without a working alternative. The replacement must:
## Deprecation Notice: [System Name]
**Status:** Deprecated as of [date]
**Replacement:** [New System] (see migration guide below)
**Removal date:** [Advisory / hard date]
**Reason:** [Why the old system is being replaced]
### Migration Guide
1. [Step-by-step migration instructions]
2. [With concrete examples]
3. [And verification commands]
For skills/workflows in this repo, use the archive pattern:
---