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.

Quality

47%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/deprecation-and-migration/SKILL.md

Quality

Discovery

67%

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

The description has a solid structure with explicit 'Use when...' clauses that clearly communicate when to select this skill. However, the capabilities described are somewhat high-level and could benefit from more concrete actions. The trigger terms cover the core domain but miss several natural variations users might employ.

Suggestions

Add more specific concrete actions such as 'writes migration guides, generates deprecation warnings, creates backward-compatible shims, plans phased rollouts'.

Expand trigger terms to include common variations like 'legacy code', 'breaking changes', 'backward compatibility', 'version upgrade', 'end-of-life', 'EOL', or 'phased rollout'.

Dimension	Reasoning	Score
Specificity	The description names the domain (deprecation and migration) and mentions some actions like 'removing old systems', 'migrating users', and 'deciding whether to maintain or sunset', but these are fairly high-level and not concrete specific actions (e.g., no mention of writing migration scripts, generating deprecation notices, versioning APIs, etc.).	2 / 3
Completeness	Clearly answers both 'what' (manages deprecation and migration) and 'when' with explicit 'Use when...' clauses covering three distinct trigger scenarios: removing old systems, migrating users between implementations, and deciding on maintenance vs sunsetting.	3 / 3
Trigger Term Quality	Includes relevant terms like 'deprecation', 'migration', 'APIs', 'sunset', and 'old systems', which users might naturally use. However, it misses common variations like 'breaking changes', 'backward compatibility', 'version upgrade', 'legacy code', 'end-of-life', or 'EOL'.	2 / 3
Distinctiveness Conflict Risk	The deprecation/migration niche is somewhat specific, but terms like 'APIs', 'features', and 'existing code' could overlap with general code maintenance, refactoring, or API design skills. The combination of deprecation + migration helps narrow it, but there's still potential for conflict with broader software engineering skills.	2 / 3
	Total	9 / 12 Passed

Implementation

27%

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

This skill reads like a well-written engineering blog post or handbook chapter rather than a concise, actionable skill file for Claude. It spends significant tokens on philosophical framing, concept explanations, and persuasive arguments that Claude doesn't need. While the migration workflow and verification checklist provide some actionable structure, the overall document is too verbose and monolithic for its purpose.

Suggestions

Cut the 'Core Principles' and 'Common Rationalizations' sections entirely — Claude already understands these concepts and doesn't need to be persuaded.

Extract migration patterns (Strangler, Adapter, Feature Flag) into a separate PATTERNS.md reference file and link to it from the main skill.

Reduce the main SKILL.md to the decision framework, the 4-step migration workflow with concrete validation checkpoints, and the verification checklist — aim for under 80 lines.

Add explicit validation gates between migration steps (e.g., 'Before proceeding to Step 3, confirm: replacement passes all integration tests AND handles 100% of documented use cases').

Dimension	Reasoning	Score
Conciseness	Extremely verbose for a skill targeting Claude. Explains concepts Claude already knows well (Hyrum's Law, Strangler Pattern, Adapter Pattern, feature flags). The 'Core Principles' section is philosophical rather than actionable. The 'Common Rationalizations' table, while interesting, is persuasive writing aimed at humans, not instructions for an AI agent. The entire document reads more like a blog post or engineering handbook chapter than a concise skill file.	1 / 3
Actionability	Contains some concrete guidance — the deprecation notice template, migration steps, code examples for adapter and feature flag patterns, and the verification checklist are useful. However, much of the content is descriptive/philosophical rather than executable. The code examples are illustrative but not copy-paste ready for a specific task. The decision framework uses prose questions rather than a concrete decision tree or script.	2 / 3
Workflow Clarity	The 4-step migration process (Build → Announce → Migrate → Remove) provides a clear sequence, and Step 4 includes a verification checklist. However, the workflow lacks explicit validation checkpoints between steps and feedback loops for error recovery. The incremental migration sub-steps mention 'verify behavior matches' but don't specify how to validate or what to do on failure beyond the generic instruction.	2 / 3
Progressive Disclosure	The entire skill is a monolithic wall of text with no references to external files and no bundle files. Content like the migration patterns, common rationalizations table, and zombie code section could be split into separate reference files. At ~200+ lines, this is far too much inline content for a SKILL.md with no progressive disclosure structure.	1 / 3
	Total	6 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Commit: f17c6e8

Reviewed: about 11 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.