# migration-architect

migration-architect — a skill for Claude Code plans staged migrations for databases, APIs, services, and infrastructure. It checks schema compatibility and prepares rollback steps before cutover.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 126 installs · ★ 1183 repo stars
- Author: borghei
- License: LicenseRef-MIT-Commons-Clause · policy=link-only · description only; the file stays with the author
- Source: https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/migration-architect/SKILL.md
- Updated: 2026-11-08
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/borghei-migration-architect

## What it does

The skill creates phased migration plans with risk assessment and validation gates, compares database or REST/JSON schemas, and prepares a reversal runbook for the cutover.

Three CLI scripts are included. `migration_planner.py` turns a JSON migration spec into a plan, `compatibility_checker.py` flags potentially breaking changes, and `rollback_generator.py` builds a runbook from the plan. The skill covers patterns such as Expand-Contract, Dual-Write, CDC, Strangler Fig, Parallel Run, Canary, and Blue-Green.

The scripts use `python3`, and the quick-start flow writes generated files outside the repository. Exit code `1` signals potentially breaking compatibility findings; `2` means the input cannot be used because a file, JSON structure, or required field is invalid.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill migration-architect -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/migration-architect/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/migration-architect/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill migration-architect -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/migration-architect/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill migration-architect -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/migration-architect/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install borghei/Claude-Skills engineering/migration-architect/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/migration-architect/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill migration-architect -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/borghei/Claude-Skills --path engineering/migration-architect
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/migration-architect/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill migration-architect -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/migration-architect/SKILL.md

## When to use it
- plan a staged database migration
- compare before-and-after API schemas
- detect breaking changes before cutover
- generate a rollback runbook from a plan
- set validation gates for a migration

## Example prompts
- Plan a database migration from `assets/sample_database_migration.json` and save the result as JSON.
- Compare `assets/database_schema_before.json` with `assets/database_schema_after.json` as database schemas.
- Generate a rollback runbook from `plan.json` with `rollback_generator.py`.

## Similar
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 127700 installs
- [migration-planner](https://affpapa.org/en/nevibecode/skills/migration-planner.md) — skill · 279 installs
- [deprecation-and-migration](https://affpapa.org/en/nevibecode/skills/deprecation-and-migration.md) — skill · 73100 installs
- [creating-oracle-to-postgres-migration-bug-report](https://affpapa.org/en/nevibecode/skills/creating-oracle-to-postgres-migration-bug-report.md) — skill · 1800 installs
- [ops](https://affpapa.org/en/nevibecode/skills/rainmanjam-ops.md) — skill · ★ 26 repo stars
- [create-database-migrations](https://affpapa.org/en/nevibecode/commands/create-database-migrations.md) — command · 329 installs

## Other versions with the same name
- [migration-architect · alirezarezvani](https://affpapa.org/en/nevibecode/skills/migration-architect.md) — 632 installs

From the same set: [borghei/claude-skills](https://affpapa.org/en/nevibecode/by/borghei/claude-skills.md) — 120 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
