Use when planning legacy system migrations, codebase modernization, monolith decomposition, microservices consolidation, cross-language rewrites, or framework upgrades. Invoke for strangler fig pattern, incremental migration strategy, or refactoring roadmaps. Do NOT use for domain analysis (use domain-analysis), component sizing (use component-identification-sizing), or step-by-step decomposition plans (use decomposition-planning-roadmap).
77
71%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./packages/skills-catalog/skills/(architecture)/legacy-migration-planner/SKILL.mdQuality
Discovery
72%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 excels at trigger term coverage and distinctiveness, particularly with its explicit 'Do NOT use for' clauses that reference adjacent skills. However, it critically lacks a statement of what the skill actually does — it reads entirely as a 'when to use' guide without describing the concrete actions or outputs the skill provides. Adding a clear 'what' clause would significantly improve it.
Suggestions
Add a leading sentence describing what the skill concretely does, e.g., 'Generates migration strategies, produces phased modernization plans, and designs incremental rewrite approaches for legacy systems.'
Ensure the description uses third-person action verbs to state capabilities (e.g., 'Plans and sequences...', 'Produces migration roadmaps...') before the 'Use when' clause.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (legacy system migrations, codebase modernization) and lists several scenarios, but it focuses more on 'when to use' triggers than on concrete actions the skill performs. It never clearly states what the skill actually does (e.g., 'generates migration plans', 'produces refactoring roadmaps'). | 2 / 3 |
Completeness | The 'when' is thoroughly covered with explicit trigger scenarios and even negative boundaries (Do NOT use for...), but the 'what does this do' is essentially missing — the description never states what actions or outputs the skill produces. | 2 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms: 'legacy system migrations', 'codebase modernization', 'monolith decomposition', 'microservices consolidation', 'cross-language rewrites', 'framework upgrades', 'strangler fig pattern', 'incremental migration strategy', 'refactoring roadmaps'. These are terms users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | The description explicitly delineates boundaries by naming three other skills that handle adjacent concerns (domain-analysis, component-identification-sizing, decomposition-planning-roadmap), making it highly distinctive and unlikely to conflict. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured planning skill with excellent workflow clarity and progressive disclosure. Its main weakness is that actionable detail is largely deferred to reference files, making the main skill body more of a routing document than a self-contained guide. There is also moderate redundancy between the Core Principles and Constraints sections.
Suggestions
Include a concrete example of what a per-domain migration plan file (e.g., 01-domain-{name}.md) should look like, even if abbreviated, so Claude has a template to follow without loading references.
Consolidate the Core Principles and Constraints sections to eliminate redundancy — the 'never assume' and 'always cite evidence' principles are restated almost verbatim in MUST DO/MUST NOT DO.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but has some redundancy — the core principles repeat constraints that appear again in the MUST DO/MUST NOT DO section (e.g., 'never assume' and 'always cite evidence' are restated). The ASCII workflow diagram is helpful but the surrounding prose could be tighter. Overall reasonable but not maximally lean. | 2 / 3 |
Actionability | The skill provides a clear process structure and specific output file paths, but the actual detailed instructions are deferred to reference files (references/research-phase.md, references/plan-phase.md, etc.). The main skill body describes what to do at a high level but lacks concrete examples of what a domain migration file should contain, what the risk matrix looks like, or what specific commands/tools to use. It's more of a framework than executable guidance. | 2 / 3 |
Workflow Clarity | The two-phase workflow (RESEARCH → PLAN) is clearly sequenced with explicit ordering ('Never skip RESEARCH. Never start PLAN without completing RESEARCH.'). Each phase has numbered steps with clear outputs. The constraint that every migration step must include a rollback strategy serves as a validation checkpoint. The workflow is well-structured with clear dependencies between phases. | 3 / 3 |
Progressive Disclosure | Excellent progressive disclosure — the skill provides a clear overview with a well-organized reference table that maps topics to specific reference files with explicit 'Load When' conditions. References are one level deep, clearly signaled, and the instruction to 'not preload all references' demonstrates thoughtful context management. The output structure is clearly laid out. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
100%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.
906a57d
Table of Contents
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.