Convex Live MigrationsSkill

Convex validates every document against the schema, which is exactly what you want until the day you add a required field to a table that already has rows in production. Then the deploy rejects the existing data and the live app breaks. This skill encodes the four-step order that avoids that, and — more usefully — states the rule that makes the order non-negotiable.

The workflow. Make the new field optional first, so the deploy accepts existing rows. Install @convex-dev/migrations and write a migration that backfills or transforms those rows. Run it and verify every row is now valid. Only then tighten the validator to make the field required.

The rules it will not let an agent skip. Never tighten a validator before the backfill completes — that is the step that rejects existing rows and takes the app down. Add new fields as optional, migrate, then require. And verify row counts on both sides of the migration rather than trusting that it ran.

It is a deliberately short skill: three paragraphs of procedure rather than a reference manual, on the theory that an agent about to alter a production schema needs an ordering constraint far more than it needs background reading. For the higher-risk version of the same job, Convex ships convex-migrate-rehearse, which runs the change against a snapshot-seeded preview deployment first and promotes it with the snapshot as a rollback.

Part of Convex's official agent-skills set. Install with npx skills add get-convex/agent-skills --skill convex-migrate.