migrate

Change the schema, the dependencies or the API without breaking prod.

Outages cluster around three kinds of change:

• a migration that locks a hot table;
• an upgrade applied from memory instead of the changelog;
• an API edit that breaks clients nobody could see.

Each skill here pairs a short, opinionated playbook with a zero-dependency checker the agent runs before anything ships. That way "is this safe?" is answered by a tool, not a guess.

| Skill | Use when | Checker | |---|---|---| | schema-migration | Writing or reviewing a DB migration: columns, indexes, constraints, type changes, backfills | lint-ddl.mjs: flags DDL that blocks writes, rewrites tables or breaks running code (Postgres, MySQL) | | dependency-upgrade | Bumping a library, framework or toolchain; applying a codemod; lockfile breakage | upgrade-report.mjs: classifies what's outdated, audits the lockfile diff, lists every import of a package | | api-contract-diff | Changing a REST/OpenAPI, GraphQL or protobuf contract | contract-diff.mjs: sorts changes into breaking, warning and safe (uses oasdiff, graphql-inspector or buf when installed) |

Install

npx @skilldeck/migrate install                 # Claude Code, user-wide
npx @skilldeck/migrate install --project       # this repo only
npx @skilldeck/migrate install --agent all     # also Codex and .agents
# or, with every SkillDeck pack available:
npx @skilldeck/cli add migrate

Claude Code marketplace: /plugin marketplace add kitasid/skilldeck, then /plugin install migrate@skilldeck.

Run the checkers yourself

They work without an agent, in CI, or in a pre-merge hook:

npx @skilldeck/migrate lint prisma/migrations                     # exit 1 on lock-heavy DDL
alembic upgrade head --sql | npx @skilldeck/migrate lint -
npx @skilldeck/migrate upgrade outdated                           # upgrade steps, majors last
npx @skilldeck/migrate upgrade usages react                       # every import and the names used
npx @skilldeck/migrate contract openapi.yaml --base origin/main   # exit 1 on breaking changes

What lint-ddl catches

On Postgres:

• CREATE INDEX without CONCURRENTLY
• ADD COLUMN ... NOT NULL without a default
• volatile or stored-generated defaults that rewrite the table
• ALTER COLUMN TYPE
• SET NOT NULL without a validated check
• foreign-key and check constraints added without NOT VALID
• unique or primary-key constraints added without a prebuilt index
• VACUUM FULL and CLUSTER
• migrations that set no lock_timeout

On MySQL, it catches MODIFY/CHANGE COLUMN and index builds without ALGORITHM or LOCK guards.

On both, it flags:

• renames
• drops
• data changes inside the migration

Tables created in the same file are exempt, since locking an empty table costs nothing. Every finding comes with the safe recipe (see skills/schema-migration/references/postgres-locks.md).

MIT licensed. Node 20+. No dependencies beyond @skilldeck/core for the installer.