| name | deprecation-and-migration |
| description | Safe deprecation of features and migration between versions. Use when removing features, changing APIs, or migrating data schemas. Covers deprecation notices, migration guides, and sunset timelines.
|
| version | 1.0.0 |
| permissions | ["fs.read","fs.write","shell.exec"] |
| triggers | [{"context":"deprecating a feature"},{"context":"removing an API endpoint"},{"context":"migrating data schemas"},{"command":"/ship"}] |
| platforms | ["claude-code","cursor","gemini-cli","copilot","codex","opencode","windsurf","kiro"] |
| dependencies | ["git-workflow-and-versioning@^1.0.0"] |
| author | codehands-core |
| signed | true |
| tier | 2 |
Overview
Deprecation is making a promise: "this will be removed, here's what to use instead, and here's how much time you have." This skill ensures deprecated features have clear notices, migration paths, and respectful timelines.
When to Use
- When removing a feature or API endpoint
- When changing a public API signature (breaking change)
- When migrating database schemas
- When replacing one library/tool with another
- NOT for internal-only changes with no external consumers
Process
1. Deprecation Notice
Before removing anything, add a deprecation notice:
function oldFunction() { ... }
2. Migration Guide
Write a migration guide:
## Migrating from v1 to v2
### Breaking Changes
1. `oldFunction()` removed → use `newFunction()`
2. `/api/v1/users` removed → use `/api/v2/users`
### Step-by-Step
1. Update import: `import { newFunction } from 'package'`
2. Replace all calls to `oldFunction(a, b)` with `newFunction({ a, b })`
3. Run tests to verify
3. Sunset Timeline
- Deprecation notice: v2.0 (current release)
- Last supported version: v2.x (minimum 1 major version)
- Removal: v3.0 (never remove in a minor/patch version)
Common Rationalizations
| Rationalization | Reality |
|---|
| "Nobody uses this feature" | If you don't have usage metrics, you don't know. Add deprecation logging first, then decide. |
| "We can just remove it" | Removing without notice breaks consumers. Even internal consumers. Deprecate first. |
Red Flags
- Removing features without deprecation notice
- Breaking changes in minor/patch versions
- No migration guide for breaking changes
- No usage metrics before deciding to deprecate
Verification
See Also
codehands:git-workflow-and-versioning — Semver for breaking changescodehands:documentation-and-adrs — ADR for deprecation decision
