deprecation-and-migration
Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code.
Security Assessment
About deprecation-and-migration
The 'deprecation-and-migration' skill provides guidance and best practices for managing the lifecycle of software systems, APIs, and features. It addresses the challenges associated with maintaining legacy code, ensuring that obsolete or redundant components are safely removed while users are migrated to newer implementations. By emphasizing the cost of maintaining code and the importance of proactive planning, this skill helps engineering teams reduce technical debt and improve long-term maintainability. It frames code not as a static asset but as a liability that requires careful evaluation of value versus ongoing costs.
The skill covers several key capabilities. It outlines principles such as treating every line of code as a liability, recognizing the constraints imposed by Hyrum's Law, and incorporating deprecation considerations from the design phase. It provides a structured decision framework for determining whether to maintain, deprecate, or sunset a system, including evaluating user dependencies, migration costs, and maintenance overhead. Additionally, it distinguishes between advisory and compulsory deprecation, detailing the appropriate mechanisms and support requirements for each. The skill also defines a clear migration process that begins with building a fully functional replacement, followed by announcing the deprecation with proper documentation and migration guidance.
This skill is particularly useful for software engineers, technical leads, and product managers involved in system maintenance and evolution. Typical use cases include replacing outdated systems or APIs, sunsetting features that no longer provide value, consolidating duplicate implementations, and planning the lifecycle of new systems with eventual deprecation in mind. By following the principles and processes outlined in this skill, teams can ensure smoother transitions, reduce the risk of breaking dependencies, and maintain a cleaner, more maintainable codebase.
FAQ
When should I use the deprecation-and-migration skill?
Use it when you need to replace old systems, APIs, or features, consolidate duplicate implementations, remove dead code, or plan the lifecycle of a new system with deprecation in mind.
How do I decide between advisory and compulsory deprecation?
Advisory deprecation is used when migration is optional and the old system is stable, relying on warnings and documentation. Compulsory deprecation is used when the old system has security issues, blocks progress, or has high maintenance costs and requires providing migration tooling and support.
Do I need a replacement system before deprecating?
Yes. The replacement must cover all critical use cases, have proper documentation and migration guides, and be proven in production before initiating deprecation.
What factors should I consider before deprecating a system?
Consider the system's unique value, the number of users depending on it, whether a replacement exists, the migration cost for each consumer, and the ongoing maintenance cost of not deprecating.
Can deprecation planning start during the design of a new system?
Yes. Designing systems with clean interfaces, feature flags, and minimal surface area makes future deprecation and migration easier and less risky.
Install deprecation-and-migration
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
addyosmani/agent-skills