Agent skill · software engineering · aiskillstore
convex-migration-helper
Plans and executes safe Convex schema and data migrations using the widen-migrate-narrow workflow and the @convex-dev/migrations component. Use this skill when a deployment fails schema validation, existing documents need backfilling, fields need adding or removing or changing type, tables need splitting or merging, or a zero-downtime migration strategy is needed. Also use when the user mentions breaking schema changes, multi-deploy rollouts, or data transformations on existing Convex tables.
Why this skill is useful
Adds specific migration patterns and commands for the Convex framework that the AI wouldn't reliably generate on its own.
What it needs
Requires @convex-dev/migrations installed locally. About 4k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Convex Migration Helper Safely migrate Convex schemas and data when making breaking changes. When to Use Adding new required fields to existing tables Changing field types or structure Splitting or merging tables Renaming or deleting fields Migrating from nested to relational data When Not to Use Greenfield schema with no existing data in production or dev Adding optional fields that do not need backfilling Adding new tables with no existing data to migrate Adding or removing indexes with no correctness concern Questions about Convex schema design without a migration need Key Concepts Schema Validation Drives the Workflow Convex will not let you deploy a schema that does not match the data at rest. This is the fundamental constraint that shapes every migration: You cannot add a required field if existing documents don't have it You cannot change a field's type if existing documents have the old type You cannot remove a field from the schema if existing documents still have it This means migrations follow a predictable pattern: widen the schema, migrate the data, narrow the schema. Online Migrations Convex migrations run online, meaning the app continues serving requests while data is updated asynchronously in batches. During the migration window, your code must handle both old and new data formats. Prefer New Fields Over Changing Types When changing the shape of data, create a new field rather than modifying an existing one. This makes the transition safer and easier to roll back. Don't Delete Data Unless you are certain, prefer deprecating fields over deleting them. Mark the field as v.optional and add a code comment explaining it is deprecated and why it existed. Safe Changes (No Migration Needed) Adding Optional Field Adding New Table Adding Index Breaking Changes: The Deployment Workflow Every breaking migration follows the same multi-deploy pattern: Deploy 1 - Widen the schema: 1. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/convex-migration-helper