How to use the Convex Schema Migration agent skill

What the convex-migrate skill makes the agent do

Agent skills are folders of instructions that an AI agent loads when a task matches them. This one covers schema changes on a deployed Convex app that already has data. Its core rule is that a validator should never be tightened before the backfill has finished, because a stricter validator would reject existing rows and break the live app.

The skill's workflow has four ordered steps: make the new field optional, install the @convex-dev/migrations package and write a migration that backfills or transforms old rows, run the migration and verify that all rows are valid, then make the field required.

• Make the new field optional first so the deploy does not reject existing rows.
• Install @convex-dev/migrations and write a backfill that makes old rows valid.
• Run the migration and verify all rows are valid.
• Tighten the validator to required only after the backfill is complete.
• Compare row counts before and after the change.

Install the convex-migrate skill

The skill ships as a ZIP download with a single file, SKILL.md. Download the ZIP from this page and unzip it into one of two locations. Use ~/.claude/skills/ to make the skill available across your projects, or use a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead, you can upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/ so the skill is available everywhere.
• Project install: unzip into the project's .claude/skills/ folder so it applies only to that repository.
• Claude apps: upload the ZIP under Settings → Capabilities → Skills.

Trigger the skill with a natural request

You do not need a special command. Describe the schema change you want in plain language and mention that the app is live or has existing data. The agent should match the request to this skill when the task is a schema change or backfill on a deployed Convex app.

Good requests name the table, the field and the reason for the change. Mentioning the existing data helps the agent choose the staged process rather than a single all-at-once edit.

• "I need to add a required field 'plan' to the users table in my live Convex app. Some users already exist, so migrate them safely."
• "Backfill the new 'slug' field on our posts table and then make it required."
• "Change the type of the 'price' field on orders and keep existing rows valid."

What you need before you start

The skill assumes a Convex project with a deployed app, the @convex-dev/migrations npm package, and access to run Convex functions against the deployment. The source does not describe other setup, so do not expect the skill to configure your deployment for you.

• A Convex project with a deployed app that contains existing data.
• The @convex-dev/migrations npm package, which the agent installs as part of the workflow.
• Access to run Convex functions against your deployment.

Safety notes: scripts and network use

This skill runs scripts and uses the network. The agent will run migration code against your deployment, so review the migration it writes before running it, and run it against a non-production deployment first if you have one. Keep a record of row counts so you can confirm the outcome.

The skill's rules say to verify row counts before and after the change, and to verify that all rows are valid before tightening the validator. Treat those checks as required, not optional.

• Review every migration script before it runs.
• Test against a non-production deployment first when one is available.
• Check row counts before and after the change.
• Do not make the field required until verification passes.

Tips for a clean migration

Keep each schema change small so each migration is easy to review. Ask the agent to report the counts it observed rather than assuming the backfill worked. If a migration fails partway, check the data before running it again instead of tightening the validator to force the deploy through.

• Change one field or one table at a time.
• Ask the agent to report row counts before and after.
• Do not skip the optional stage, even when the backfill looks simple.