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 migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

73%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A thorough, actionable skill body with strong workflow sequencing and validation for destructive/batch operations, notably the expand/contract migration guidance. Its main weakness is redundancy between the principles, rationalizations table, and red flags that inflates the token budget.

Suggestions

Consolidate the Common Rationalizations table and Red Flags list with the Core Principles — they restate the same deprecation/expand-contract rules and could be merged to cut tokens.

Trim the 'Code Is a Liability' section, which largely repeats the Overview paragraph, to a single sentence pointing at the principle.

Consider moving the detailed migration patterns (Strangler, Adapter, Feature Flag) and the rationalizations into reference files under references/ so SKILL.md stays a lean overview.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and assumes Claude's competence (no basic explanations of databases/APIs/migrations), but the Common Rationalizations table and Red Flags list restate concepts already covered in the principles and expand/contract rules, and the 'Code Is a Liability' section repeats the Overview, so it could be tightened.	3 / 5
Actionability	Provides executable code blocks (Adapter, Feature Flag patterns), a near copy-paste expand/contract worked example, and named commands (CREATE INDEX CONCURRENTLY, npx migrate-check, the down migration) — mostly executable with only minor illustrative-vs-template gaps.	4 / 5
Workflow Clarity	The four-step migration process and the 5-step expand/contract example are clearly sequenced and independently reversible, with explicit validation/feedback loops (tested down path before merge, bake after switch reads, rollback if a phase misbehaves) and verification checklists for both deprecation and schema migrations.	5 / 5
Progressive Disclosure	No bundle files exist, so navigation is via clean section headers across a single ~240-line file; structure is good and one-level (no nested or broken references), though some content (detailed patterns, rationalizations, red flags) could plausibly split into reference files.	4 / 5
	Total	16 / 20 Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, well-constructed description that clearly states the skill's purpose and supplies several concrete, naturally-worded triggers. It is distinct from sibling skills and only marginally short of full trigger synonym coverage.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions across the domain — removing systems/APIs/features, migrating users between implementations, migrating a DB schema via expand/contract, and deciding maintain-vs-sunset — giving comprehensive coverage rather than vague abstraction.	5 / 5
Completeness	Explicitly answers 'what' ('Manages deprecation and migration') and 'when' via multiple concrete 'Use when...' clauses, satisfying the what-and-when requirement at the top anchor.	5 / 5
Trigger Term Quality	Includes natural trigger phrases users would say ('removing old systems', 'migrating users', 'renaming or dropping a column without downtime', 'maintain or sunset') with good synonym coverage, but a few natural terms (decommission, refactor, deprecate) are absent.	4 / 5
Distinctiveness Conflict Risk	The deprecation/migration lifecycle niche is distinct with specific triggers unlikely to fire for unrelated skills, though minor overlap with general refactoring or code-quality skills is possible.	4 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Path: skills/deprecation-and-migration/SKILL.md
Commit: 48cb116

Reviewed: ~19 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.