Guide · Agent skill

How to use the Convex Backup and Restore Drill agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The convex-backup skill is an agent skill: a SKILL.md instruction file that tells an AI coding agent how to back up a Convex app and then prove the backup can be restored. It is for developers running a Convex app who want a tested backup rather than an export file sitting on a disk. After this guide you will know how to install the skill, ask for a backup or drill in plain language, and read the result.

Convex Backup and Restore Drillopenclaw/clawhub · MIT Download the skill

Quick start

1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
2Confirm your requirements. Check that Node.js and the Convex CLI are available, you have deploy access, and you have a Preview Deploy Key as CONVEX_DEPLOY_KEY or a personal dev deployment to fall back on.
3Ask for a backup and drill. Tell the agent in plain language that you want your Convex app backed up and the restore tested. Name the goal so the skill is picked up.
4Let the agent take the snapshot. The agent runs npx convex export to write a backup file and treats it as sensitive data.
5Review the restore drill result. Check that the agent restored into a throwaway preview and verified row counts and sample records. Treat a failed drill as the key finding.
6Set the schedule and retention. Agree on a backup cadence that matches how much data loss you can accept, and a retention window, using storage you control.
7Keep the runbook. Save the recovery runbook the agent writes, and use it only with the deployment safety gate in place.

What the convex-backup skill makes the agent do

The skill covers two halves of a backup. First it takes a snapshot export of your Convex data with the Convex CLI and sets up a schedule matched to how much data loss you can tolerate, which is your RPO. Second, and the main feature, it runs a restore drill: the agent restores the snapshot into a disposable preview deployment, checks that row counts and sample records came back, and reports whether recovery actually worked.

The skill also writes a gated recovery runbook with the commands to restore to production. Restores to production are gated by a deployment safety check, and the runbook notes that writes made after the snapshot will be lost.

Install the convex-backup skill

You can install the skill from the ZIP on the page. Download the ZIP, then unzip it into one of these locations:

Your personal skills folder: ~/.claude/skills/

A single project's skills folder: .claude/skills/ inside the project

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills. The skill ships as a single file, SKILL.md.

Personal: unzip into ~/.claude/skills/
Per project: unzip into .claude/skills/ in your project root
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before you start

The commands are specific to the Convex CLI, so the skill only helps with Convex apps. Make sure you have the following before asking for a drill.

Node.js with the Convex CLI, run through npx convex
A Convex project where you have deploy access
A Preview Deploy Key set as CONVEX_DEPLOY_KEY. This is a paid-tier feature.
Or a personal dev deployment to use as a fallback if preview keys are not available. The fallback is less representative of production.
Convex MCP tools, if you want row-count checks
Durable storage you control for scheduled copies, such as CI or cron storage

Trigger the skill with natural requests

You do not need special syntax. Describe what you want in plain language and the agent will pick up the skill when the request matches its description. Good requests name the goal: a backup, a schedule, a restore test, or a recovery runbook.

The skill's rules say the agent should always run or offer to run the restore drill, not just take the export.

Back up my Convex app and prove I can restore it.
Run a restore drill on my Convex data into a preview.
Set up a daily Convex export to storage I control, keeping 14 days.
Write a recovery runbook for restoring my Convex production data.

Understand the restore drill steps

The drill is the part most people skip. The agent follows these steps and reports the outcome plainly.

First it classifies and announces the deployment being backed up. Reading and exporting are safe, but the restore target is always a throwaway preview, never production. Then it takes the snapshot and creates a preview from the current code. It imports the snapshot into that preview and reads the data back to check it.

A restore that completes but lands 0 rows counts as a failed drill. A failed drill is the most useful result, because you find the problem before a real disaster.

Take the snapshot with npx convex export
Create a throwaway preview from the current code
Import the snapshot into that preview with --replace
Check critical-table row counts and a sample of real records against the source

npx convex export --path backup-<date>.zip
npx convex deploy --preview-create restore-drill-<date>
npx convex import backup-<date>.zip --deployment restore-drill-<date> --replace

Read the report and keep your backups safe

At the end the agent reports what was backed up, whether the restore was actually performed and verified, the recommended schedule and retention window, and the recovery runbook. The runbook contains the exact production restore command, which the skill says must be gated by the deployment safety check.

Snapshots are real data. The skill tells the agent to delete local snapshot copies when the work is done and never to commit a backup file to version control. The drill preview expires automatically.

Delete local snapshot copies when finished
Never commit backup files to git
Keep a user-owned copy alongside Convex's platform backups

npx convex import backup.zip --replace --prod

What people use it for

Proving a Convex app can be restored before a disaster, by running a drill into a preview and checking row counts.
Setting a daily snapshot export to CI or cron storage you control, with a retention window matched to your RPO.
Finding a broken backup early because a restore landed 0 rows in the drill.
Writing a recovery runbook that lists the exact restore commands and the caveat about writes made after the snapshot.
Preparing a disaster recovery rehearsal for a team that wants the restore tested rather than assumed.

Frequently asked questions

Is the convex-backup skill free?

The skill is released under the MIT licence, as listed on this page. The drill's main requirement is a Preview Deploy Key, which is a paid-tier feature of Convex, so the full drill depends on your Convex plan. If you lack that, the drill can fall back to a personal dev deployment.

What do I need to install convex-backup?

You need Node.js with the Convex CLI (npx convex), a Convex project where you have deploy access, and a place to unzip the skill. The skill ships as a ZIP containing SKILL.md, which you place in ~/.claude/skills/ or a project's .claude/skills/ folder.

Does the skill work with apps that are not on Convex?

No. The commands are specific to the Convex CLI, so the skill is for Convex apps only. Apps on other databases need a backup approach built for their own tools.

Is this the same as migrate-rehearse?

No. The restore drill reuses the same snapshot and preview steps as the separate migrate-rehearse skill, but it aims them at recovery. Forward schema or data migrations belong to migrate-rehearse, not this skill.

What happens if I don't have a Preview Deploy Key?

The skill says to drill against a fresh personal dev deployment instead and to state that this was done. A dev deployment is less representative of production, so the result is a weaker test.

Does the skill run scripts and use the network?

Yes. The skill runs scripts and uses the network, because it calls the Convex CLI to export, deploy a preview and import data. Review the commands it proposes, keep snapshots out of version control, and rely on the deployment gate before any production restore.

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

Use convex-backup if you run a Convex app and want a backup you have actually restored, with a drill that checks row counts and records. Skip it if your app is not on Convex, if you only need forward migrations (use migrate-rehearse), or if you cannot get a Preview Deploy Key and are not satisfied with a dev deployment fallback.

Download the skill