Guide · Agent skill
How to use the Convex Migration Helper agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-migration-helper skill is a set of instructions and reference files that teaches an AI agent how to plan a safe change to a live Convex app's schema or data. It is for developers who need to add a required field, change a field type, or split a table without breaking records that already exist. After following this guide you will know how to install the skill, ask for help with a natural request, and what the agent will walk you through.
Convex Migration Helperopenclaw/clawhub · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the convex-migration-helper ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
- 2Describe your schema change. Ask the agent in plain language, for example that you need to make a field required or split a table, and mention whether the app is live.
- 3Widen the schema and update code. Follow the agent's plan to allow both old and new formats, handle both on read, and write the new format on create. Then deploy.
- 4Install the migrations component. Run npm install @convex-dev/migrations and register it in convex/convex.config.ts as the skill's reference describes.
- 5Dry run the migration. Test the migration with npx convex run migrations:myMigration '{"dryRun": true}' before changing real records.
- 6Run and monitor the migration. Run npx convex run migrations:myMigration, watch its status, and confirm every document has been migrated.
- 7Narrow the schema and clean up. Require the new format in the schema, remove the old-format code, deploy, then remove the migration code once stable.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file and optional reference files. When you ask a compatible AI agent a relevant question, it reads the skill and follows its guidance. This skill is named convex-migration-helper and focuses on breaking changes to Convex schemas and data.
The skill makes the agent follow a multi-step plan called widen, migrate, then narrow. First the schema is widened so it accepts both old and new data. Existing records are then backfilled in batches, and finally the schema is tightened to the new format only. The skill also points to the @convex-dev/migrations component and to common code patterns.
- Explains why Convex rejects a deploy when existing documents do not match the schema
- Plans the multi-deploy workflow and a checklist for your change
- Recommends a dry run (dryRun: true) before touching production records
- Provides patterns for adding required fields, deleting fields, changing types, splitting nested data, and cleaning up orphaned documents
Install the skill from the ZIP or the Claude apps
Download the ZIP for convex-migration-helper from this page. You have two options.
For Claude Code, unzip the download into your personal skills folder ~/.claude/skills/ for use across projects, or into a project's .claude/skills/ folder to share it with that project only. The skill folder should contain SKILL.md and the references folder.
In the Claude apps, you can upload the skill instead under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. Describe the change you want in plain language and mention the kind of work involved. The skill's description covers breaking schema changes, backfills, table reshaping, and zero-downtime rollouts, so requests using those ideas are the most likely to trigger it.
Include details about your existing data and whether the app is live. The more the agent knows about what is already stored, the better the plan will be.
- "I need to make the role field on users required. Plan a zero-downtime migration for my Convex app."
- "We're splitting the nested address object on orders into its own table. Walk me through a safe backfill."
- "Help me change the price field from a string to a number without breaking existing documents."
- "Review my migration for backfilling a new field and check I'm not using .collect() on a large table."
Run the migration safely with the migrations component
For any non-trivial migration the skill recommends the @convex-dev/migrations component. It handles batching, cursor-based pagination, state tracking, resume from failure, dry runs, and progress monitoring. Install it with npm in your project, then register it in convex/convex.config.ts and create a Migrations instance in convex/migrations.ts, as shown in the component reference the skill points to.
Define each migration with migrateOne, which processes a single document while the component handles batching. Before running it for real, test with a dry run, then run it and watch its status.
- Install: npm install @convex-dev/migrations
- Dry run: npx convex run migrations:myMigration '{"dryRun": true}'
- Live run: npx convex run migrations:myMigration
npm install @convex-dev/migrations
npx convex run migrations:myMigration '{"dryRun": true}'
npx convex run migrations:myMigrationFollow the two-deploy workflow
Every breaking migration follows the same pattern. In the first deploy you widen the schema so it allows both formats, update code to read both and write the new format, then deploy. Between deploys you run the migration and verify every document has been migrated. In the second deploy you narrow the schema to the new format only, remove the old-format code, and deploy.
Do not skip the write-new-format step. Documents created during the migration window would otherwise be missed.
- Deploy 1: widen the schema, handle both formats on read, write the new format on create
- Between deploys: backfill existing documents and verify
- Deploy 2: require the new format, delete the old-format code, deploy
- Finally remove the migration code once the change is stable
Avoid common pitfalls
The most frequent mistake is making a field required before the data has been migrated, which causes Convex to reject the deploy. Another is using .collect() on a large table, which can hit transaction limits or time out. Use the migrations component's batched pagination instead, and reserve .collect() for tables you know are small.
When removing data, prefer deprecating a field by marking it v.optional and adding a comment explaining why it existed. Delete it only when you are confident the data is no longer needed and no code references it.
- Widen the schema before making a field required
- Avoid .collect() on large tables
- Write the new format before running the migration
- Deprecate fields rather than deleting them early
- Don't use crons for migration batches; the component handles batching
What people use it for
- Making a previously optional field required on a live users table by backfilling defaults in batches
- Splitting a nested object stored on documents into a separate relational table with a zero-downtime rollout
- Changing a field's type, such as string to number, by writing a new field first and migrating existing values
- Cleaning up orphaned documents that reference records which no longer exist
- Reviewing an existing migration plan for missing dry runs, unbatched .collect() calls, or premature field deletion
Frequently asked questions
Is the convex migration helper skill free to use?
The skill is published under the MIT licence, as stated on this page. The @convex-dev/migrations component is a separate package you install with npm, and you should check its own terms before relying on it.
What do I need to use this skill?
You need a Convex project, since the skill targets Convex schemas and functions. The recommended batched approach requires the @convex-dev/migrations component, plus Node/npm and the Convex CLI because the guide references npx convex run commands.
Do I need this skill for adding an optional field?
No. The skill states that adding optional fields, adding new tables with no existing data, and adding indexes need no migration. It is designed for breaking changes to data that already exists.
Does the skill run scripts or use the network?
According to the skill's metadata, it runs no scripts and uses no network access. It provides instructions and reference files that the agent reads; any commands you run are ones you execute yourself in your project.
Can I use this skill with a database other than Convex?
No. The guidance and code examples are specific to Convex, including its schema validation and the migrations component, so it will not apply to other databases.
What should I do if my deploy is rejected after changing a schema?
This usually happens when a field is made required before existing documents have it. The skill's first rule is to widen the schema first, backfill the data, and only then require the new format.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill is a good fit if you maintain a live Convex app and need a careful, checklist-driven plan for changing data that already exists, with dry runs before production. It is not worth the extra deploy steps for a new project, simple optional fields or indexes, or any database other than Convex.
Download the skill