convex-backup Skill for Claude Code: What It Does and How to Install It
Makes Claude back up a Convex deployment and prove the backup works by restoring it into a throwaway preview.
- Installs
- 38.4K
- on skills.sh
- Stars
- 68
- on GitHub
- Updated
- Oct 2026
- last repo commit
This skill makes Claude take a Convex snapshot export and then test the restore. It recommends a backup schedule that fits how much data loss you can accept, restores the snapshot into a throwaway preview deployment and reads the data back to check it. A restore that lands zero rows counts as a failed drill, and the skill is told to report that loudly.
The drill needs a Preview Deploy Key set as CONVEX_DEPLOY_KEY, which SKILL.md calls a paid-tier feature. Without one it drills against a fresh personal dev deployment and says so. It calls deploy-guard first and reuses the snapshot and preview steps of migrate-rehearse. Its folder holds only SKILL.md.
Good for
- Teams running a Convex app in production who want a tested recovery plan
- Developers who have exports but have never tried restoring one
Install convex-backup
Claude Code
- 1
Copy this prompt.
Install the convex-backup skill in Claude Code. Run this command: npx skills add https://github.com/convex/agent-skills --skill convex-backup --skill convex-deploy-guard Then check that it loaded and tell me how to use it.
- 2
Paste it into Claude Code. It shows the change and asks before running it.
Requires Node.js.
SKILL.md hands work to convex-deploy-guard, so the first command installs it too. It also mentions convex-migrate-rehearse as optional hand-offs; install those separately if you want them. Convex's docs say the skills CLI installs skills into .agents/skills/ in your project. The "All Convex skills" command installs every skill in the repo, which has 33 skill folders. One of them, convex-improve-convex-plugin, is listed in the Convex docs as sending your coding session's transcript to the Convex team. Run this skill with /convex-backup in Claude Code or $convex-backup in Codex, or let the agent pick it when the task fits. This skill reads your deployment through the official Convex MCP server, which is not part of the skills. Add the server command to your client's MCP settings; the Convex docs also describe an official plugin that starts it for you. This skill works on your project folder, so this page offers no Claude app upload route.
Built from the package data we hold. Not yet tested by us.
What's in the skill
When it loads
Set up Convex backups and run a restore DRILL that proves recovery — snapshot, restore into a throwaway preview, assert the data came back — plus a schedule matched to your RPO and a gated recovery runbook.
Sections in SKILL.md
- Workflow
- Rules
Key facts
- Installs on skills.sh
- 38,358 (Nov 2, 2026)
- Last repo commit
- Oct 29, 2026
- Audits on skills.sh
- Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes
Uses deploy-guard to classify and announce the deployment before it runs anything
Read ·
Guard the targetRuns npx convex export --path backup-<date>.zip, with --include-file-storage for files
SKILL.md calls the zip sensitive real data.
Runs code ·
Take the snapshotSuggests a cadence matched to tolerable data loss, such as a daily export from CI or cron
SKILL.md describes a user-owned, portable copy kept alongside Convex's own platform backups, with a retention window.
Recommend a scheduleCreates a throwaway preview, then imports the snapshot with --replace into it
Commands: npx convex deploy --preview-create restore-drill-<date>, then npx convex import backup-<date>.zip --deployment restore-drill-<date> --replace.
Try: “Back up this Convex app and prove I can restore it”
Runs code ·
Run the restore drillReads the restored tables back and compares row counts and sample records
Uses the Convex MCP tools tables, data and runOneoffQuery.
Network ·
Assert recoveryStates whether the drill passed, plus the schedule and the exact restore commands
The prod restore is npx convex import backup.zip --replace --prod, gated by deploy-guard, with the loss of writes made after the snapshot stated.
Report and write the runbookDeletes local snapshot copies when done and never commits a backup file
Delete ·
Clean up
From the official docs
Permissions
Medium risk
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only mode
Watch out for
The snapshot zip holds your real data
SKILL.md says to treat the export as sensitive, delete local copies when done and never commit it. Keep it out of git and out of shared folders. github.com
The restore overwrites its target
The drill runs npx convex import with --replace against a named deployment. Check that the name is the restore-drill preview before you approve the command. github.com
The production restore command is in the runbook
SKILL.md lists npx convex import backup.zip --replace --prod as the recovery command, gated by deploy-guard, and says writes made after the snapshot are lost. Do not run it without that confirmation. github.com
The Convex MCP server limits production access by default
The Convex docs say the MCP server is safe by default: in production deployments agents cannot access PII and can only perform read-only operations. Write access and PII reads on production need --dangerously-enable-production-deployments or --cautiously-allow-production-pii. docs.convex.dev
Security advisories
No published security advisories as of Nov 2, 2026.
Technical details
| Turning on read-only | SKILL.md defines no read-only mode. It says reading and exporting is safe and that the restore target is a throwaway preview. |
|---|---|
| Sign-in and keys | SKILL.md expects the Preview Deploy Key in the CONVEX_DEPLOY_KEY environment variable. |
| Scopes |
|
Questions
What does convex-backup do?
It makes Claude export a Convex snapshot, suggest a backup schedule and then test the restore. The test restores the snapshot into a throwaway preview deployment and checks that the critical tables came back with the expected rows.
Does the drill touch my production data?
SKILL.md says the drill restores into a throwaway preview, or a fresh dev deployment, and never into prod. The export reads the source deployment. The production restore appears only as a runbook command, gated by deploy-guard.
What do I need to run it?
A Preview Deploy Key exported as CONVEX_DEPLOY_KEY, which SKILL.md describes as a paid-tier feature, so the drill can create a preview. If you do not have one, it drills against a fresh personal dev deployment instead. The Convex MCP tools are used to read the restored data back.
How do I install it?
Use the install box at the top of this page. The first command installs convex-backup together with convex-deploy-guard, which SKILL.md uses to classify the deployment. convex-migrate-rehearse is an optional companion: this skill reuses its snapshot and preview mechanics, and its commands are spelled out in this SKILL.md. Run it with /convex-backup in Claude Code or $convex-backup in Codex.
Is it safe?
A snapshot holds real data, and the drill runs an import with --replace, which overwrites the target deployment. Check that the --deployment name is the preview before approving. SKILL.md says to delete local snapshots when done and never commit one. Our advice: add backup zips to .gitignore.
How is it different from convex-migrate-rehearse?
Both use a snapshot export, a preview deployment and an import. migrate-rehearse points them at a forward schema change, and convex-backup points them at recovery.
Does it replace Convex's own backups?
SKILL.md says Convex's platform backups exist and that this skill adds a copy you own, plus a tested restore.
Is it official?
It sits in the convex/agent-skills repo under the Convex GitHub organisation, which is the vendor's own repo. Convex's docs list that repo as the Convex agent skills.
Information
updated Nov 2, 2026
- Repository
- convex/agent-skills
- Folder
skills/convex-backup
Sources
Docs, issue trackers and discussions this page is built from.
Show all 5Hide
- convex/agent-skills README · github.com
- skills CLI commands · github.com
- Convex docs: Agent Skills · docs.convex.dev
- convex-backup SKILL.md · github.com
- Convex docs: MCP server · docs.convex.dev