convex-migrate-rehearse Skill for Claude Code: What It Does and How to Install It

Makes Claude try a Convex schema change and backfill on a preview seeded with a prod snapshot before touching prod.

Installs: 38.4K; on skills.sh
Stars: 68; on GitHub
Updated: Oct 2026; last repo commit

This skill makes Claude rehearse a schema change on a copy of your production data. Convex fails a schema push if any existing row does not fit the new schema, and the skill lets that failure happen on a preview. It exports a prod snapshot, creates a preview from the pre-change code, imports the snapshot there and runs the change in order: optional field, push, backfill, verify, tighten, push.

It promotes to prod only on your fresh explicit yes, and it keeps the snapshot as the rollback. Previews need a Preview Deploy Key set as CONVEX_DEPLOY_KEY, which SKILL.md calls a paid-tier feature. Without one it rehearses on your personal dev deployment. It calls deploy-guard and the migrate skill. Its folder holds only SKILL.md.

Good for

Convex developers changing the schema of an app that already has live data
Teams who want a failed migration to happen on a copy, not on prod

Install convex-migrate-rehearse

Claude Code

Copy this prompt.

Install the convex-migrate-rehearse skill in Claude Code. Run this command:

npx skills add https://github.com/convex/agent-skills --skill convex-migrate-rehearse --skill convex-deploy-guard

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

SKILL.md hands work to convex-deploy-guard, so the first command installs it too. It also mentions convex-migrate as optional hand-offs; install those separately if you want them. Convex's docs say the skills CLI installs skills into .agents/skills/ in your project. The "All Convex skills" command installs every skill in the repo, which has 33 skill folders. One of them, convex-improve-convex-plugin, is listed in the Convex docs as sending your coding session's transcript to the Convex team. Run this skill with /convex-migrate-rehearse in Claude Code or $convex-migrate-rehearse in Codex, or let the agent pick it when the task fits. This skill reads your deployment through the official Convex MCP server, which is not part of the skills. Add the server command to your client's MCP settings; the Convex docs also describe an official plugin that starts it for you. This skill works on your project folder, so this page offers no Claude app upload route.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

Rehearse a live-app schema change + backfill on a snapshot-seeded preview deployment, verify, then promote the proven change to prod with the snapshot as rollback.

Sections in SKILL.md

Workflow
Rules

Key facts

Author: Convex (GitHub organisation convex; the vendor's own repo)
License: Apache-2.0 (stated in the README and the LICENSE file)
Installs on skills.sh: 38,365 (Nov 2, 2026)
GitHub stars: 68 for the whole convex/agent-skills repo (Nov 2, 2026)
Last repo commit: Oct 29, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 1 file: SKILL.md (the repo tree lists nothing else in the folder)
Part of: The convex/agent-skills repo: 33 skill folders in the tree. The README names 6 skills, and this one is not among them

What it includes

Needs a Preview Deploy Key in CONVEX_DEPLOY_KEY, else uses your personal dev deployment
Read · Check the preview key
deploy-guard names the prod source and target and gets your yes for the promote up front
Read · Guard the source and target
Runs npx convex export --path snapshot.zip (add --include-file-storage for files)
Runs code · Snapshot the source data
Deploys the old code with --preview-create, then imports the snapshot with --deployment
SKILL.md says to do this before editing schema.ts, so the import still fits the old schema. The preview expires after about 5 days.
Runs code · Create and seed the preview
Makes the field optional, pushes, backfills with @convex-dev/migrations, tightens, pushes
Each push is npx convex deploy --preview-name migrate-<slug>. The push fails on the copy if a row does not fit.
Try: “Rehearse this schema change on a preview before we touch prod”
Runs code · Rehearse the change
Runs the app's functions against the migrated data with MCP run or a smoke query
Network · Verify on the preview
Repeats the same sequence on prod, only after your fresh explicit yes
The rollback is npx convex import snapshot.zip --replace --prod. Data written after the snapshot is lost, so SKILL.md says to keep the window short.
Runs code · Promote to prod
Lets the preview expire and deletes the local snapshot, which is never committed
Delete · Clean up

From the official docs

Permissions

High risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can change production data and schema
The final step applies the migration to prod. SKILL.md gates it behind a fresh explicit yes, and the rollback loses writes made after the snapshot. Do not approve it without reading the plan. github.com
The snapshot zip holds real data
SKILL.md says to treat it as sensitive, delete it when finished and never commit it. github.com
Imports and rollbacks can overwrite a deployment
The rollback uses npx convex import with --replace and --prod. Check the target on every import command. github.com
The Convex MCP server limits production access by default
The Convex docs say the MCP server is safe by default: in production deployments agents cannot access PII and can only perform read-only operations. Write access and PII reads on production need --dangerously-enable-production-deployments or --cautiously-allow-production-pii. docs.convex.dev

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	SKILL.md defines no read-only mode. The snapshot step is a read, and the prod promote needs a fresh explicit yes.
Sign-in and keys	SKILL.md expects the Preview Deploy Key in the CONVEX_DEPLOY_KEY environment variable.
Scopes	Exports a snapshot of your production data to a local zip Creates a preview deployment and imports the snapshot into it Pushes schema changes and runs a backfill, then repeats them on prod after your yes Uses a Preview Deploy Key from the CONVEX_DEPLOY_KEY environment variable

Questions

What does convex-migrate-rehearse do?

It makes Claude test a schema change and data backfill on a preview deployment that holds a snapshot of your production data. Only after that run is green does it apply the same sequence to prod.

Will it change production by itself?

SKILL.md says the prod promote needs a fresh explicit yes through deploy-guard, asked for up front. The snapshot step is described as a read of the source deployment, and the rehearsal pushes and imports go to the preview.

Do I need a paid Convex plan?

Previews need a Preview Deploy Key, which SKILL.md calls a paid-tier feature. If you have none, it falls back to your personal dev deployment seeded with the snapshot and tells you.

What if the promote goes wrong?

SKILL.md keeps the snapshot as the rollback artifact, restored with npx convex import snapshot.zip --replace --prod. It states plainly that data written after the snapshot is lost, so keep the promote window short.

How do I install it?

Use the install box at the top of this page. The first command installs convex-migrate-rehearse together with convex-deploy-guard, which SKILL.md uses to classify the prod source and target. convex-migrate is an optional hand-off for the optional-then-tighten pattern; install it separately if you want it. Run it with /convex-migrate-rehearse in Claude Code or $convex-migrate-rehearse in Codex.

Is it safe?

It exports real data to a local zip and runs imports that can overwrite a deployment, then can push to prod. SKILL.md says to delete the snapshot when done and never commit it. Read every deploy and import command, and check the target name each time.

How is it different from convex-migrate?

SKILL.md says plain optional-then-tighten guidance with no live data is the migrate skill. This one adds the snapshot, the preview rehearsal and the guarded promote.

Is it official?

It is in the convex/agent-skills repo under the Convex GitHub organisation, which is the vendor's own repo.

Information

updated Nov 2, 2026

Repository: convex/agent-skills
Folder: skills/convex-migrate-rehearse

convex/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

convex/agent-skills README · github.com
skills CLI commands · github.com
Convex docs: Agent Skills · docs.convex.dev
convex-migrate-rehearse SKILL.md · github.com
Convex docs: MCP server · docs.convex.dev