Migration Pattern for Handling Deprecations in Agent-Skills: A Four-Step Guide

The addyosmani/agent-skills repository defines a four-step migration pattern for handling deprecations that requires building a replacement first, announcing with documentation, migrating consumers incrementally, and finally removing the old system only after full migration is verified.

Managing deprecations safely requires a disciplined approach to minimize downstream risk. The addyosmani/agent-skills repository codifies a specific migration pattern for handling deprecations within its Deprecation and Migration skill. This pattern ensures that agents retire systems methodically while maintaining stability for dependent consumers.

The Four-Step Migration Pattern

According to skills/deprecation-and-migration/SKILL.md, agents must follow four sequential phases when deprecating any system, API, or feature.

Step 1: Build the Replacement

Before initiating any deprecation work, ensure a fully-functional alternative exists. The replacement must cover all critical use cases, include proper documentation, and be proven in production environments. As defined in the skill file at line 69, agents should never announce a deprecation until this replacement stability is achieved.

Step 2: Announce and Document

Publish a formal deprecation notice that specifies status, replacement details, removal date, and rationale. Provide a comprehensive migration guide outlining exact code changes and any required migration scripts. The skill file at line 77 mandates that this documentation include:

## Deprecation Notice: OldService

**Status:** Deprecated as of 2025-03-01  
**Replacement:** NewService (see migration guide below)  
**Removal date:** Advisory — no hard deadline yet  
**Reason:** OldService requires manual scaling and lacks observability.  
NewService handles both automatically.

### Migration Guide

1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the migration verification script: `npx migrate-check`

Step 3: Migrate Incrementally

Move consumers one at a time rather than executing a "big-bang" switch. For each consumer, identify all touch-points with the deprecated system, update them to use the new replacement, and verify the migration script succeeds. According to line 94 in the skill file, this incremental approach minimizes risk and allows for rapid rollback if issues arise.

Step 4: Remove the Old System

Once every consumer has been migrated and the new system is stable, retire the old codebase. This final phase, documented at line 108, requires cleaning up configuration and deleting remaining artifacts only after migration verification is complete.

Implementation Commands

The following bash commands illustrate the practical execution of this migration pattern for handling deprecations:

# 1. Verify replacement works

npm test && npx start-new-service

# 2. Publish deprecation notice (Markdown example shown above)

# 3. Run migration for a single consumer

npx migrate-check --consumer=my-app

# 4. After all consumers are migrated, delete old code

git rm -r src/old-service
git commit -m "Remove deprecated OldService"

Key Resources and File Paths

The migration pattern for handling deprecations is defined in the following locations within the addyosmani/agent-skills repository:

File	Role
skills/deprecation-and-migration/SKILL.md	Complete definition of the four-step workflow, including line-specific guidance for each phase (lines 69, 77, 94, 108)
skills/deprecation-and-migration/examples.md	Sample migration guides and code snippets (if present)
README.md	Overview of the deprecation-and-migration skill within the repository's skill index

Summary

• The migration pattern for handling deprecations in agent-skills consists of four mandatory steps: build replacement, announce/document, migrate incrementally, and remove old system.
• Never announce a deprecation until a production-ready replacement exists with full documentation.
• Migrate consumers one at a time to minimize risk and enable rapid rollback if issues occur.
• Remove deprecated code only after all consumers have migrated and verification scripts pass.

Frequently Asked Questions

What is the migration pattern for handling deprecations in agent-skills?

The repository defines a four-step pattern: first build a fully-functional replacement, then announce the deprecation with comprehensive documentation, next migrate consumers incrementally one at a time, and finally remove the old system once all migrations are verified. This pattern is codified in skills/deprecation-and-migration/SKILL.md.

When should a deprecation notice be published according to the skill?

A deprecation notice should only be published after the replacement system is fully built, documented, and proven in production. As specified at line 69 in SKILL.md, agents must never announce a deprecation until the alternative covers all critical use cases and is production-ready.

How does the pattern minimize risk during migration?

The pattern minimizes risk by requiring incremental migration of consumers rather than a "big-bang" approach. By moving one consumer at a time and verifying each with scripts like npx migrate-check, teams can identify issues early and roll back specific changes without affecting the entire system.

What constitutes the final step in the deprecation workflow?

The final step is removing the old system, which occurs only after every consumer has been migrated and the new system is stable. According to line 108 in SKILL.md, this involves retiring the old codebase, cleaning up configuration, and deleting remaining artifacts following successful verification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}