migration-architect
by alirezarezvanimigration-architect helps plan zero-downtime database, service, and infrastructure migrations with phased execution, compatibility validation, data reconciliation, and rollback runbooks. Includes scripts for migration plans, compatibility checks, and rollback generation for Software Architecture teams.
This skill scores 84/100, which means it is a solid listing candidate for directory users planning complex migrations. The repository provides enough trigger clarity, workflow substance, scripts, sample assets, and expected outputs for an agent to do more than a generic prompt, though adopters should expect to adapt generated plans and fill in organization-specific details.
- Clear trigger scope: the frontmatter explicitly targets database migrations, infrastructure cutovers, system replacements, and high-risk transitions needing rollback paths.
- Substantive workflow assets: three scripts cover migration plan generation, compatibility checking, and rollback runbook generation, supported by sample inputs and expected outputs.
- Good install-decision evidence: reference docs cover migration patterns, zero-downtime techniques, and data reconciliation strategies, giving users a concrete view of the skill's methodology.
- No install command is present in SKILL.md, so users may need to infer setup from the repository layout and README examples.
- Generated runbook examples still contain placeholders such as TBD contacts and generic validation commands, so production use requires customization and review.
Overview of migration-architect skill
What migration-architect is for
The migration-architect skill helps plan high-risk software, database, service, and infrastructure migrations where downtime, data loss, API breakage, or rollback ambiguity would create business risk. It is most useful when you need more than a generic migration checklist: phased execution, compatibility validation, cutover planning, data reconciliation, and a rollback runbook that operations teams can actually follow.
Best-fit users and migration scenarios
Use the migration-architect skill if you are a software architect, staff engineer, platform engineer, SRE, database lead, or technical program owner preparing a production transition. It fits PostgreSQL or other database upgrades, monolith-to-service moves, strangler-fig service replacement, cloud cutovers, schema evolution, API versioning, and migrations with compliance constraints such as GDPR, SOX, or PCI DSS.
What makes this skill different
The repository includes practical support beyond prompt text: scripts/migration_planner.py, scripts/compatibility_checker.py, and scripts/rollback_generator.py, plus sample database and service migration specs. The reference files cover migration patterns, zero-downtime techniques, and data reconciliation strategies, which makes the skill stronger for Software Architecture decisions than a one-off “make me a plan” prompt.
Adoption considerations
This skill is strongest when you can provide real constraints: downtime budget, dependencies, schema changes, traffic profile, data volume, compliance requirements, validation gates, and rollback triggers. It is not a substitute for environment-specific testing, load testing, database engine expertise, or formal change approval. Treat its output as an architecture planning accelerator, not an automatic production authorization.
How to Use migration-architect skill
migration-architect install and first files to read
Install the skill in a Claude Skills-compatible environment with:
npx skills add alirezarezvani/claude-skills --skill migration-architect
Then inspect the skill at:
engineering/skills/migration-architect
Read README.md first for the component map and quick-start commands, then SKILL.md for the intended workflow. Review assets/sample_database_migration.json and assets/sample_service_migration.json before writing your own input because they show the level of detail the scripts and prompts expect. Use expected_outputs/ to understand the shape of useful deliverables before asking for customized output.
Inputs that make migration-architect usage effective
A weak prompt says: “Plan our database migration.” A stronger prompt gives the skill decision-grade context:
- migration type: database, service, infrastructure, or hybrid
- source and target platforms, versions, and hosting model
- downtime limit and data-loss tolerance
- data volume, row counts, table criticality, or request load
- dependent services, clients, jobs, queues, analytics, and backups
- schema or API changes, including breaking-change concerns
- compliance, audit, retention, and encryption requirements
- success metrics, validation queries, rollback triggers, and owner roles
Example prompt:
“Use the migration-architect skill to create a phased zero-downtime migration plan for PostgreSQL 13 on-prem to PostgreSQL 15 managed cloud. Data volume is 2.5 TB. Max downtime is 30 minutes. Critical dependencies are authentication, notification, analytics, and backups. Include compatibility risks, validation gates, reconciliation checks, rollback criteria, and a stakeholder communication timeline.”
Using the included scripts
The README shows command-line usage for generating plans and reports. A typical workflow is:
python3 scripts/migration_planner.py \
--input assets/sample_database_migration.json \
--output migration_plan.json \
--format both
Use scripts/compatibility_checker.py with before/after schema files such as assets/database_schema_before.json and assets/database_schema_after.json to surface compatibility risks. Use scripts/rollback_generator.py after the migration plan exists so rollback steps align with planned phases rather than generic failure handling.
Practical workflow for better plans
Start by copying one sample asset into your own migration spec, then replace every placeholder with production facts. Ask the skill for an initial plan, then separately request a compatibility report, a rollback runbook, and a cutover checklist. Compare the result with expected_outputs/sample_database_migration_plan.txt, schema_compatibility_report.txt, and rollback_runbook.txt to see whether your output is specific enough for review by engineering, SRE, security, and business owners.
migration-architect skill FAQ
Is migration-architect only for database migrations?
No. The repository includes database and service migration examples. The database path is especially concrete because it includes before/after schema assets and compatibility checking, but the service example supports strangler-fig migration, endpoint compatibility, load profile changes, client dependencies, and session continuity.
How is this better than an ordinary migration prompt?
An ordinary prompt often produces a plausible checklist. The migration-architect skill is structured around migration patterns, zero-downtime techniques, compatibility analysis, data reconciliation, and rollback generation. The included scripts and expected outputs make it easier to create artifacts that resemble engineering runbooks rather than strategy notes.
Can beginners use the migration-architect skill?
Yes, but beginners should start from the sample JSON files and avoid skipping constraints. The skill can teach the planning shape, but it assumes you can identify systems, dependencies, data stores, operational limits, and validation needs. If those facts are unknown, use the first pass to generate discovery questions before asking for a final plan.
When should I not use this skill?
Do not rely on migration-architect alone for emergency live recovery, vendor-specific database tuning, legal compliance signoff, or changes that require deep access to proprietary infrastructure. It is also a poor fit for trivial migrations with no production users, no compatibility risk, and no rollback requirement.
How to Improve migration-architect skill
Improve migration-architect results with sharper constraints
The most common failure mode is a plan that sounds complete but cannot be executed. Prevent that by giving hard numbers: maximum downtime, RPO/RTO, data size, peak traffic, batch windows, replication lag tolerance, rollback time limit, and who can approve each gate. Replace vague phrases like “minimal downtime” with measurable thresholds such as “no more than 5 minutes of write unavailability.”
Add validation and reconciliation details
For database work, include primary keys, row counts, critical tables, schema changes, indexes, constraints, and representative validation queries. For service work, include endpoint lists, expected status codes, compatibility promises, traffic split strategy, latency targets, and client versions. The skill performs better when it can turn these facts into gates, smoke tests, and reconciliation checks.
Iterate from plan to runbook
Do not stop at the first migration plan. Ask for a risk review, then a rollback runbook, then an operator checklist. A useful follow-up prompt is: “Review this plan for hidden coupling, missing validation gates, rollback ambiguity, and data reconciliation gaps. Return only changes that would reduce production risk.” This turns migration-architect from a planner into a review assistant.
Extend the repository for your environment
To improve the migration-architect skill for repeated internal use, add organization-specific templates: approval gates, incident contacts, cloud provider commands, database backup procedures, observability dashboards, feature flag standards, and post-cutover monitoring checks. Keep these as reusable reference files rather than burying them in one prompt so future migration plans inherit the same operational standards.