Skip to content
Convex Live Migrations

Convex Live Migrations Skill

Convex's official skill for changing the schema of a deployed app without breaking it — add the field optional, backfill with @convex-dev/migrations, verify, then tighten the validator.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from get-convex/agent-skills.

$ npx skills add get-convex/agent-skills --skill convex-migrate

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/convex-migrate/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/convex-migrate/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Four-step order: optional field, backfill, verify, then require
  • Uses @convex-dev/migrations for the backfill
  • Blocks tightening a validator before the backfill completes
  • Verifies row counts before and after
  • Points at convex-migrate-rehearse for a preview-first, rollback-backed variant

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.

Try it

Once installed, ask your agent something like:

I need to add a required organizationId to the users table on a live Convex deployment — plan and run the migration safely.

SKILL.md

The instructions your agent loads, as published by Convex.

SKILL.md
name
convex-migrate
description
Migrate schema + backfill data on a deployed Convex app using @convex-dev/migrations.

<!-- GENERATED from convex-agents content/capabilities/migrate.json — do not edit by hand. -->

Migrate the schema / data on a live app

Change a deployed schema without breaking existing data: stage the schema change, install @convex-dev/migrations, write a backfill that makes old rows valid, run it, and verify before tightening the validator.

Workflow
  1. Make the new field optional first (so deploy doesn't reject existing rows).
  2. Install @convex-dev/migrations; write a migration that backfills/transforms existing rows.
  3. Run the migration; verify all rows are valid.
  4. Tighten the validator (make the field required) once the backfill is complete.
Rules
  • Never tighten a validator before the backfill completes — it rejects existing rows and breaks the live app.
  • Add new fields as optional first, migrate, then require.
  • Verify row counts before and after.
Install

Skill: Convex

by Convex

Featured

Convex's official top-level agent skill — routes an agent to the right convex-* skill for the task and to a served capability catalogue that stays current without a reinstall.

New

Convex's official skill for turning a one-sentence app idea into a running Next.js + Convex template with an anonymous dev deployment, plus strict rules for writing Convex functions that compile and push first time.

Convex's official skill for adding passkey or OAuth authentication to a Convex app — including the auth.config.ts wiring and a headless key-generation path that avoids the interactive wizard.

Prisma's official skill for migrating an ORM project from v6 to v7 - the prisma-client generator, driver adapters, prisma.config.ts, ESM entrypoints and every removed API.

Browse all skills →