| name | deprecation-and-migration |
| description | Use when retiring an old path, replacing a legacy behaviour or moving users to a new interface or workflow. |
Deprecation and Migration
When to use
Use this skill when removing or replacing a skill, doc path, workflow, API surface or other user-facing behaviour that still has active dependents.
Objective
Remove old paths safely by providing a clear replacement, a controlled transition period and a verified end state.
Procedure
- Identify what is being replaced and why.
- Define the replacement path and compatibility expectations.
- Mark the old path clearly with deprecation guidance.
- Migrate dependents in small, observable steps.
- Remove the old path only after usage is confirmed to be gone or intentionally waived.
Rules
- Do not delete a legacy path before the replacement is valid.
- Do not surprise users with a silent incompatibility break.
- Do not leave parallel paths undocumented.
- Do not treat migration as complete until the old path is no longer needed.
Example
When replacing an old skill path, add the new path first, update references, leave a short deprecation note where users will find the old entry and run a search for dependants. Remove the old path only after consumers have moved or the user explicitly accepts the compatibility break.
References
Verification
