migration-refactor-specialist

Skill para migracoes, modernizacao de legacy e refactors estruturais. Use quando precisar fazer upgrades grandes, extracao incremental, strangler pattern, compatibilidade de transicao e rollout seguro. Trigger em: "migracao de framework", "modernizacao de legacy", "strangler pattern", "refactor estrutural", "upgrade grande", "extracao incremental", "migracao de runtime", "trocar ORM", "rollout incremental de refactor", "migrar para".

Quality

52%

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/23-migration-refactor-specialist/SKILL.md

Quality

Discovery

82%

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

This is a reasonably well-constructed skill description that excels in completeness by providing explicit 'Use quando' and 'Trigger em' clauses. The trigger term coverage is strong with many natural Portuguese phrases users would say. The main weakness is that the capabilities described are somewhat abstract—listing patterns and concepts rather than concrete actions the skill performs.

Suggestions

Replace abstract domain references with concrete actions, e.g., 'Generates step-by-step migration plans, creates adapter layers for backward compatibility, produces rollback strategies' instead of just naming patterns.

Clarify boundaries with general refactoring skills by specifying what distinguishes this skill, e.g., 'For large-scale cross-system migrations only, not small code refactors or single-file improvements.'

Dimension	Reasoning	Score
Specificity	The description names the domain (migrations, legacy modernization, structural refactors) and mentions some techniques (strangler pattern, incremental extraction, safe rollout), but doesn't list concrete actions like 'generates migration plans', 'creates compatibility layers', or 'produces rollback scripts'. The actions remain somewhat abstract.	2 / 3
Completeness	The description explicitly answers both 'what' (migrations, legacy modernization, structural refactors, incremental extraction, strangler pattern, transition compatibility, safe rollout) and 'when' with a clear 'Use quando' clause and an explicit 'Trigger em' list with specific scenarios.	3 / 3
Trigger Term Quality	The description includes an explicit list of natural trigger terms in Portuguese that users would actually say: 'migracao de framework', 'trocar ORM', 'migrar para', 'strangler pattern', 'upgrade grande', etc. Good coverage of variations and common phrasings.	3 / 3
Distinctiveness Conflict Risk	While terms like 'strangler pattern' and 'migracao de framework' are fairly distinctive, terms like 'refactor estrutural' and 'upgrade grande' could overlap with general refactoring or code improvement skills. The niche is reasonably clear but not perfectly delineated from broader refactoring skills.	2 / 3
	Total	10 / 12 Passed

Implementation

22%

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

This skill reads more like a role description or ticket template than an actionable guide for performing migrations. It lacks any concrete examples, code snippets, step-by-step workflows, or specific techniques (strangler pattern implementation, feature flag strategies, dual-write patterns, etc.) that would make it useful for executing complex migrations. The referenced external files (policies, templates) may contain the missing substance, but the SKILL.md body itself provides almost no executable guidance.

Suggestions

Add a concrete, sequenced workflow with numbered steps for executing a migration (e.g., 1. Audit current state → 2. Define boundary → 3. Implement adapter layer → 4. Validate with dual-run → 5. Cut over → 6. Remove legacy), including explicit validation checkpoints at each phase.

Include at least one concrete example showing a migration pattern (e.g., strangler fig with feature flags, or an incremental ORM swap) with actual code or pseudocode that demonstrates the approach.

Add a rollback procedure with specific steps and validation criteria, not just 'rollback documentado' — show what a rollback checkpoint looks like in practice.

Provide a concrete migration plan template inline (or ensure templates/migration-plan.md exists in the bundle) with filled-in example sections so Claude knows exactly what output format to produce.

Dimension	Reasoning	Score
Conciseness	The content is moderately efficient but includes some sections that are somewhat redundant or could be tightened. The 'Evidencia de Conclusao' section largely repeats the 'Checklist Base', and the 'Quando Usar'/'Quando Nao Usar' sections restate what's already in the description. However, it doesn't over-explain concepts Claude already knows.	2 / 3
Actionability	The skill is entirely abstract and descriptive — it contains no concrete code, commands, templates, examples, or executable steps. It describes what should happen ('plano incremental de migracao') but never shows how to actually do it. There are no strangler pattern examples, no feature flag code, no migration script templates, no concrete rollback procedures.	1 / 3
Workflow Clarity	There is no clear sequenced workflow for performing a migration. The checklist is a flat list of concerns rather than an ordered process with validation checkpoints. For a skill dealing with high-risk, multi-step structural changes, the absence of explicit phases, validation gates, and feedback loops is a significant gap.	1 / 3
Progressive Disclosure	The skill references several external files (GLOBAL.md, multiple policies, templates/migration-plan.md) which suggests an attempt at progressive disclosure. However, no bundle files are provided to verify these exist, and the SKILL.md itself doesn't contain enough substantive content to serve as a useful overview — it's mostly metadata with little actionable core content to build from.	2 / 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: felvieira/claude-skills-fv
Commit: 7577622

Reviewed: 3 days 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.