CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

migration-architect

Zero-downtime migration planning, compatibility validation, and rollback strategy generation. Tools for system, database, and infrastructure migrations with minimal business impact. Use when planning a database migration, infrastructure cutover, system replacement, or any high-risk transition that needs explicit rollback paths.

56

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./engineering/skills/migration-architect/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

45%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.

The Quick Start is exemplary — a chained, gate-enforced plan → compatibility-check → rollback workflow with real scripts and sample assets — but it is buried in a ~370-line encyclopedia of migration patterns Claude already knows, none of which points to the bundle's own reference files (which are therefore dead weight), and one cited path (expected_outputs/) does not exist. The file needs to invert its structure: keep the workflow, link out the catalogs.

Suggestions

Replace the inlined Migration Patterns, Rollback Strategies, and Risk Assessment sections with short summaries plus one-level-deep links to the existing references/ files (e.g., 'Pattern catalog: See references/migration_patterns_catalog.md'), which currently are never mentioned in SKILL.md and are undiscoverable.

Delete generic-knowledge content Claude already knows (Expand-Contract, Strangler Fig, canary, blue-green, CDC explanations, the risk-category taxonomy, and the Tools and Technologies section that restates the Quick Start) to cut the body to roughly the Quick Start plus navigation.

Fix or remove the dangling 'expected_outputs/' reference (the directory does not exist in the bundle), and either complete the MigrationCircuitBreaker/MigrationFeatureFlag examples so they are executable or move them into a reference file.

DimensionReasoningScore

Conciseness

Of 428 lines, roughly 370 explain patterns Claude already knows in detail — Expand-Contract, Strangler Fig, Parallel Run, Canary, Blue-Green, CDC, Lift-and-Shift, circuit breakers, risk categories, generic best-practices lists — plus padded restatement (the Overview and closing paragraph repeat the description verbatim in spirit, and 'Tools and Technologies' restates the Quick Start scripts). Not a 1 because the Quick Start section is genuinely lean and information-dense; clearly below the midpoint because the padding dominates the file.

2 / 5

Actionability

The Quick Start is fully executable (real commands chaining migration_plan.json → compatibility.json → rollback_runbook with concrete asset paths), but it covers only ~20 lines; the remaining bulk is descriptive pattern prose, and the inline code is incomplete — MigrationCircuitBreaker calls self.new_service, self.fallback_to_legacy, self.should_attempt_reset, self.on_success/on_failure without defining them, so it cannot run. Not a 4 because the majority of the body instructs at the direction level ('Track performance and error rates') rather than providing executable steps; above a 2 because the core workflow does give copy-paste commands.

3 / 5

Workflow Clarity

The primary workflow is clearly sequenced with an explicit validation gate: outputs chain between steps, 'exits non-zero unless fully compatible (CI gate)', the migration 'is not approved until' compatibility passes or breaking items are accepted in writing and a rollback runbook exists per phase, with a feedback loop ('Re-run both checks after any schema revision'). Not a 5 because the secondary processes (During-Migration runbook: 'Execute rollback if success criteria not met') leave success criteria and rollback triggers implicit, and the promised expected_outputs shapes for verification are absent.

4 / 5

Progressive Disclosure

The bundle ships three large reference files (migration_patterns_catalog.md, zero_downtime_techniques.md, data_reconciliation_strategies.md — ~99KB combined) but the body never mentions or links any of them, so they are undiscoverable; meanwhile ~300 lines of pattern-catalog content that clearly belongs in those files (and likely duplicates them) are inlined in SKILL.md. The body also cites an 'expected_outputs/' directory that does not exist in the bundle. This matches the anchor for inlined content plus buried references; it reaches a 2 rather than 1 only because section headers and the Quick Start provide some structure.

2 / 5

Total

11

/

20

Passed

Description

83%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 description with a clear what, an explicit multi-trigger 'Use when' clause, and good natural keyword coverage. It is only marginally short of exemplar quality due to a few missing common synonyms (cloud/data/schema migration) and a trigger clause broad enough to invite minor overlap with deployment-related skills.

DimensionReasoningScore

Specificity

Lists several concrete actions — "Zero-downtime migration planning, compatibility validation, and rollback strategy generation" — plus the migration domains ("system, database, and infrastructure migrations"). Not a 5 because the actions are process-level rather than fully concrete operations (e.g., no mention of generating migration plans/runbooks from specs, the skill's actual executable capability), and no 3 because multiple distinct specific actions are named, not just 1-2.

4 / 5

Completeness

Clearly answers both: the what ("Zero-downtime migration planning, compatibility validation, and rollback strategy generation... Tools for system, database, and infrastructure migrations") and an explicit when clause ("Use when planning a database migration, infrastructure cutover, system replacement, or any high-risk transition that needs explicit rollback paths"). The when lists multiple concrete trigger scenarios, matching the anchor-5 example structure; a 4 would require a vaguer 'when' than what is present.

5 / 5

Trigger Term Quality

Natural triggers include "database migration", "infrastructure cutover", "system replacement", and "rollback paths" — phrases users would realistically say. Not a 5 because common variations are missing: "cloud migration", "data migration", "schema migration/change", "zero-downtime deploy"; not a 3 because coverage goes beyond one or two generic keywords and includes several natural phrasings.

4 / 5

Distinctiveness Conflict Risk

The migration-with-rollback niche ("Zero-downtime migration planning... rollback strategy generation") is clearly distinct from generic processing skills. Not a 5 because "any high-risk transition that needs explicit rollback paths" is broad enough to overlap with deployment/release-management and refactoring skills; not a 3 because the core triggers (database migration, cutover, system replacement) are specific to this niche.

4 / 5

Total

17

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

alirezarezvani/claude-skills

Path

engineering/skills/migration-architect/SKILL.md

Reviewed

Table of Contents

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.