How to use the Rehearse Convex Schema Migrations skill

What the skill makes the agent do

A schema push on Convex checks every existing document against the new schema and fails if any row does not conform. This skill avoids finding that out on production. The agent copies a production snapshot into a temporary preview deployment, applies the schema change and a data backfill there, checks the result, and only then repeats the same steps on prod.

The skill also keeps the snapshot as a rollback artifact and reminds the agent to delete the local copy of the real data when finished.

Install the skill from the ZIP

Download the ZIP from the skill's page on this site and unzip it. The skill file is SKILL.md. Put the unzipped folder in one of these locations:

• Personal skills folder: ~/.claude/skills/
• Project-only skills folder: .claude/skills/ inside your project
• Or, in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there

Check the requirements before you start

The workflow depends on preview deployments, so you need more than the skill itself. The source lists these requirements:

• Convex CLI, run through npx convex
• A Convex account with a Preview Deploy Key, exported as CONVEX_DEPLOY_KEY. A plain npx convex login session cannot create previews, and preview deployments are a paid-tier feature
• The @convex-dev/migrations library installed in your app
• Access to the production deployment for export and promotion

Get a Preview Deploy Key

The agent needs a preview key before it runs any deploy that uses --preview-create or --preview-name. You create it in the Convex dashboard under Project Settings, then Deploy Keys, then Preview. Export it as CONVEX_DEPLOY_KEY.

If you do not have a preview key, the skill can fall back to rehearsing on your personal dev deployment seeded with the snapshot. The skill says so when it does this, but that rehearsal is weaker because it is not a preview deployment.

Trigger the skill with a natural request

You do not need special syntax. Describe the change and the fact that real data is involved. The skill is meant for requests like these:

• Add a required field to my users table, but I have live data, so rehearse it on a preview first
• Backfill the new status column on my orders table safely before we deploy to prod
• Tighten the validator on this field, and test the migration on a copy of production data first

Follow the workflow the agent runs

The agent works through these stages. Each stage happens in order, and the prod promote only happens after you give a fresh explicit yes.

• Guard: the agent names the source (prod, read only) and the target (prod, to be changed), then asks for your explicit yes for the promote and confirms the plan
• Snapshot: the agent exports production data read only. This changes nothing on prod
• Create the preview from the pre-change code, before editing schema.ts, so the preview matches the schema the data already conforms to
• Seed the preview by importing the snapshot into it
• Rehearse on the preview using the migrate order: optional field, push, backfill, verify, tighten, push
• Verify the migrated data with your app functions or a smoke query
• Promote the same sequence to prod, keeping the snapshot as rollback
• Clean up the preview and delete the local snapshot

Commands the agent uses

These are the commands from the skill source. The agent runs them for you, but you can read them to see what will happen. The snapshot export is a read and changes nothing:

Preview create, seed and deploy commands

The preview is created from the old code, seeded with the snapshot, and then re-deployed to on each rehearsal step. Import targets the preview by name with --deployment, not with --preview-name. Each deploy uses --preview-name so it keeps the same preview data.

• Create: npx convex deploy --preview-create migrate-<slug>
• Seed: npx convex import snapshot.zip --deployment migrate-<slug>
• Rehearse steps: npx convex deploy --preview-name migrate-<slug>

Promote to prod and keep the rollback

After the preview run is green and you say yes, the agent repeats the same sequence on prod. The source says the prod push is a repeat of a run that already worked on prod-shaped data, not a new attempt. The rollback command is:

• Rollback: npx convex import snapshot.zip --replace --prod
• Warning: restoring the snapshot loses any data written after the snapshot was taken, so keep the promote window short

Safety notes: scripts, network and sensitive data

This skill runs scripts and uses the network. It runs Convex CLI commands that export and deploy data, and it talks to your Convex deployments. Review the commands before you approve the promote step.

The exported snapshot holds real data. The skill tells the agent to treat it as sensitive, to delete it locally when finished, and never to commit it to version control. Backfills should go through @convex-dev/migrations, which is batched, resumable and can be dry-run, rather than one-shot mutations over a whole table.

• Never commit snapshot.zip to a repository
• Delete the local snapshot when the work is done
• The preview expires automatically, so you do not need to clean it up by hand

Tips for a smoother run

Keep the rehearsal and the promote close together so the snapshot stays current. If the optional-field push fails on the preview, read the offending shape the error reports, fix the data handling, and re-push to the same preview until it passes. Only add the --include-file-storage flag to the export when the migration touches stored files, since the source only calls for it in that case.

• Use the preview for every failed push first, so prod never sees a failure
• If the change is small and you have no live data, use the plain migrate guidance instead