How do I install the Migration Surgeon skill?

Run npx skillmds@latest add willianbs/migration-surgeon in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Migration Surgeon safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Migration Surgeon?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Migration Surgeon free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Migration Surgeon?

willianbs (@willianbs) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Migration Surgeon by willianbs — Agent Skill

Name: Migration Surgeon
Author: willianbs

Migration Surgeon

Plans safe schema/data migrations with expand/contract, backfill, and rollback. Use for DB/search/queue shape changes. Emits MIGRATION_PLAN. Never recommends destructive one-shot prod migrations without a rollback path.

willianbs 9e8dab2 2 files · 3.4 KB Updated Sep 17, 2026

File contents

Purpose

Deliver schema and data changes without downtime or irreversible damage.

When to Use / When NOT to Use

Use when: SQL/NoSQL schema changes, backfills, reindexes, dual-writes, storage format changes.

Do not use when: code-only refactors with no data shape change; trivial nullable additive column with no backfill (lite plan OK).

Preconditions

Current schema/model and desired end state (or diff). Prod-size awareness if available.

Inputs / Outputs

Inputs: schema diff / models, IMPACT_REPORT, CONTEXT_PACK, deploy constraints.

Outputs: MIGRATION_PLAN

Upstream / Downstream

Upstream: delivery-planner, change-impact-analyzer, api-contract-guardian.

Downstream: feature-implementer, quality-gate (deploy), observability-designer, pr-generator.

Core Principles

Expand/contract over big-bang rewrites.
Rollback is mandatory for High+ risk.
Backfills are paced and observable; lock/timeout aware.
Dual-write/read windows when readers are heterogeneous.
Never destroy data in the same step that deploys new code unless explicitly approved.
Idempotent migration steps preferred.
Do not run prod migrations unless user explicitly asks.

Process

Current vs target shape; classify Additive | Transform | Destructive.
Phase plan: expand → migrate/backfill → cutover → contract.
Per-phase: deploy order, feature flags, validation queries, abort criteria.
Lock/performance risk; batch sizes; estimated duration (label confidence).
Rollback per phase.
Observability hooks (row counts, error rate).
Decision.

Evidence Requirements

Cite migration files/models. No fake row counts — mark Unknown.

Stop Conditions / Failure Modes

Condition	Action
Destructive drop without expand/contract or backup plan	Block
No rollback for High risk	Block
User requests prod execute without approval trail	Refuse

Severity + Confidence

Destructive prod data risk → Critical until mitigated.

Output Contract

## MIGRATION_PLAN
Type: Additive | Transform | Destructive
Phases: ...
Backfill: ...
Rollback: ...
Validation: ...
Observability: ...
Decision: Proceed | ProceedWithConditions | Revise | Block

Handoffs

feature-implementer, observability-designer, quality-gate, change-impact-analyzer.

Never

Never DROP/TRUNCATE as step 1 in prod plans.
Never skip backup/rollback for Destructive.
Never invent production row counts.

---name: migration-surgeondescription: Plans safe schema/data migrations with expand/contract, backfill, and rollback. Use for DB/search/queue shape changes. Emits MIGRATION_PLAN. Never recommends destructive one-shot prod migrations without a rollback path.---# PurposeDeliver schema and data changes without downtime or irreversible damage.# When to Use / When NOT to Use**Use when:** SQL/NoSQL schema changes, backfills, reindexes, dual-writes, storage format changes.**Do not use when:** code-only refactors with no data shape change; trivial nullable additive column with no backfill (lite plan OK).# PreconditionsCurrent schema/model and desired end state (or diff). Prod-size awareness if available.# Inputs / Outputs**Inputs:** schema diff / models, IMPACT_REPORT, CONTEXT_PACK, deploy constraints.**Outputs:** `MIGRATION_PLAN`# Upstream / Downstream**Upstream:** delivery-planner, change-impact-analyzer, api-contract-guardian.**Downstream:** feature-implementer, quality-gate (deploy), observability-designer, pr-generator.# Core Principles1. Expand/contract over big-bang rewrites.2. Rollback is mandatory for High+ risk.3. Backfills are paced and observable; lock/timeout aware.4. Dual-write/read windows when readers are heterogeneous.5. Never destroy data in the same step that deploys new code unless explicitly approved.6. Idempotent migration steps preferred.7. Do not run prod migrations unless user explicitly asks.# Process1. Current vs target shape; classify Additive | Transform | Destructive.2. Phase plan: expand → migrate/backfill → cutover → contract.3. Per-phase: deploy order, feature flags, validation queries, abort criteria.4. Lock/performance risk; batch sizes; estimated duration (label confidence).5. Rollback per phase.6. Observability hooks (row counts, error rate).7. Decision.# Evidence RequirementsCite migration files/models. No fake row counts — mark Unknown.# Stop Conditions / Failure Modes| Condition | Action ||-----------|--------|| Destructive drop without expand/contract or backup plan | Block || No rollback for High risk | Block || User requests prod execute without approval trail | Refuse |# Severity + ConfidenceDestructive prod data risk → Critical until mitigated.# Output Contract```## MIGRATION_PLANType: Additive | Transform | DestructivePhases: ...Backfill: ...Rollback: ...Validation: ...Observability: ...Decision: Proceed | ProceedWithConditions | Revise | Block```# Handoffs**feature-implementer**, **observability-designer**, **quality-gate**, **change-impact-analyzer**.# Never- Never DROP/TRUNCATE as step 1 in prod plans.- Never skip backup/rollback for Destructive.- Never invent production row counts.

Frequently asked questions