How to use the Convex Migration Lifecycle Guide agent skill

What the skill makes the agent do

A skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This one covers the full lifecycle of a Convex migration, backfill, destructive cleanup, or one-off maintenance function: design the change, write and validate the code, open a pull request, deploy, run a dry run, wait for approval, apply the change, verify it, and then remove the temporary code.

The skill is built around explicit stop points. The agent is told to wait for explicit user confirmation in the current thread before any destructive production apply step and before it removes the migration code. It also asks the agent to report deployment names, cursors, PR URLs, and final stats in a handoff.

Install the skill

You can install the skill in either of two ways. Download the ZIP from the directory page and unzip it into one of these locations: ~/.claude/skills/ for your user account, or .claude/skills/ inside a project folder if you want it limited to that project.

Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

Trigger the skill with natural requests

You do not need a special command. Ask for the full lifecycle or a specific part of it in plain language, and the agent will match the request against the skill's description. The skill's own description mentions end-to-end migrations, backfills, destructive cleanups, and one-off maintenance functions.

Requests that should match include asking for a complete production backfill with its PR, deploy, dry run, apply, and cleanup, or asking for a cleanup that removes a field or table in production. Be specific about the change and the deployment so the agent can classify the work correctly.

• Implement a backfill that sets the new ownership field on existing records, then run it through the full migration lifecycle.
• Plan and run a destructive cleanup that removes an old table in production, with dry run and apply gates.
• Write a one-off maintenance function for a data repair, then remove it after it has been verified.

What it needs before you start

The skill is not portable. It depends on repository-specific files and skills that are not included in the package, so it will not work as written in other projects. The source lists these requirements: a Convex project using the @convex-dev/migrations component, which the skill recommends; the Bun runtime with repository scripts such as bunx convex codegen, bun run ci:static, and bun run ci:unit; access to Convex production deployments and GitHub pull requests; and three companion skills, convex-migration-helper, clawhub-convex, and clawhub-production-release, which are not included here.

The skill does not run scripts itself and does not use the network according to its listing. It is licensed under MIT.

Safety notes

The skill is designed to pause for a human. Running it without someone reviewing the dry-run and apply results would defeat its safety gates. The agent is also told to pin production commands to the explicit deployment name when that is known, rather than relying on a generic production flag, and to call out any change that could affect visibility, moderation, ownership, billing, installability, or public API output before the apply gate.

Because the skill asks the agent to run production dry runs and applies through the repository's tooling, use it only with credentials and deployment access you are authorised to use, and review each command the agent proposes before approving it.

Tips for getting good results

Name the deployment and the change clearly in your first message. Keep dry runs and applies in bounded batches, as the skill instructs. Keep the resume cursors and run IDs the agent reports, since the handoff relies on them. When the agent says it is waiting for confirmation, check the dry-run counts and sample IDs before you reply.

• Confirm the classification the agent gives (code deploy, function run, import/export, schema narrowing, data cleanup, or cleanup-code removal) before any implementation starts.
• If the agent cannot run real Convex validation locally, ask it to record the blocker and state how the PR compensates.
• Do not approve a cleanup PR until the apply results and verification proof are in the handoff.