Guide · Agent skill
How to use the Convex Deployment Guard agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Convex Deployment Guard is an agent skill, a set of instructions your AI coding agent loads from a SKILL.md file, that makes it check and announce which Convex deployment it is about to touch before running any command that could change it. It is aimed at developers who work on several Convex projects or deployments on one machine, and at teams that want an agent unable to change production by accident. After this guide you will know how to install the skill, how to ask for it in plain language, and what it will and will not do.
Convex Deployment Guardopenclaw/clawhub · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the convex-deploy-guard ZIP from our page and unzip it. The skill is a single SKILL.md file inside the folder.
- 2Place it where your agent looks. Move the folder into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm your Convex setup. Check that CONVEX_DEPLOYMENT is set in .env.local and/or convex.json, and that the Convex CLI is available through npx convex.
- 4Ask for the target. Ask the agent which deployment it is pointing at. It should identify the target and announce it in one line.
- 5Give explicit consent for prod. For any production change, review what the agent says will change and reply with a clear yes for that specific action.
- 6Use read-only when needed. Say 'read-only' or 'don't change anything' to lock the session. The agent will then avoid deploys, env changes, mutations and imports.
What the skill makes the agent do
Convex apps often have several deployments, such as a personal dev deployment, preview deployments and production. A command sent to the wrong one is a common source of mistakes. With this skill active, the agent first identifies the deployment it points at by reading CONVEX_DEPLOYMENT in .env.local and convex.json, and checking whether CONVEX_DEPLOY_KEY is set, or by calling the official Convex MCP status tool. It classifies the target as local-anonymous, dev, preview or prod.
Before any deployment-affecting command, the agent states the target in one line, for example: target: dev (joyful-capybara-123, personal dev). Production actions need a fresh, explicit yes for that specific action in the current session. A session can also be set to read-only.
- Identifies the target before acting, and stops if two sources disagree.
- Announces the target in one line before deploy, env, import/export or similar commands.
- Requires a fresh explicit yes for production deploys, env set on prod, snapshot import/export on prod, and running prod MCP access.
- Honors a read-only request for the rest of the session, including 'harmless' mutations.
- If a deploy seems to do nothing, re-checks the target instead of deploying again.
Install the skill (ZIP download or Claude apps upload)
The skill ships as a single file, SKILL.md. Download the ZIP from our page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into your project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. Ask in plain language, and the agent will apply the guard before any deployment-affecting step. Stating your intent clearly helps, especially when you want read-only behaviour or a production audit.
The skill's own rules say its workflow runs as step 0 for other deploy-related skills that ship, env, migrate and seed. Those skills call this guard first; it is not a deploy tool on its own.
- 'Which Convex deployment are you pointing at right now?'
- 'Deploy my changes to dev and tell me the target first.'
- 'Don't change anything in this session. Read-only from now on.'
- 'Audit production data and logs, but do not enable production changes.'
Examples of a guarded workflow
A typical exchange starts with the agent identifying and announcing the target, then waiting for confirmation before acting on production. The example announcement format comes from the skill's own text.
When the request is a read-only production audit, the skill says to start the MCP server with the read-only prod flag only, and to keep the mutating flag off unless you explicitly ask to change production.
- Dev deploy: agent reports target: dev (<name>, personal dev), then runs the command.
- Prod deploy: agent lists exactly what will change on which deployment and asks for a yes in this session.
- Prod audit: agent uses --cautiously-allow-production-pii for read tools only.
- Read-only session: agent starts the MCP with --disable-tools run,envSet,envRemove.
target: dev (joyful-capybara-123, personal dev)What the skill needs and what it does not do
You need a Convex project with CONVEX_DEPLOYMENT in .env.local and/or convex.json. The workflow refers to Convex CLI commands run via npx convex. The official Convex MCP server is optional and is needed only for the status tool and the MCP flags.
The skill runs no scripts and makes no network calls of its own. It only gives the agent instructions. The commands it guards, such as npx convex deploy, are the ones that can affect your deployments, so the safety value comes from the agent stopping to confirm first.
- Requires: Convex project, CONVEX_DEPLOYMENT in .env.local and/or convex.json, Convex CLI (npx convex).
- Optional: official Convex MCP server for the status tool and MCP flags.
- Runs scripts: no. Uses network: no.
- Licence: MIT.
Safety notes on MCP flags and production
The two production MCP flags are different risk levels and the skill keeps them separate. --cautiously-allow-production-pii enables read tools for a production audit. --dangerously-enable-production-deployments enables mutating production tools and should stay off unless you explicitly ask to change production in this session.
Production consent is per action and per session. A yes given earlier, or for a different target, does not carry over. The skill also says to default every MCP start to a non-prod deployment selector, such as --deployment dev.
- Read audit: --cautiously-allow-production-pii only.
- Mutating prod: --dangerously-enable-production-deployments only on explicit request.
- Default MCP scope: non-prod, for example --deployment dev.
- Ambiguous target: the agent stops and checks rather than guessing.
Tips for getting the most from it
Keep CONVEX_DEPLOYMENT set in .env.local and convex.json so the agent can classify the target without guessing. If the sources disagree, resolve that first.
When a deploy seems to have changed nothing, do not ask the agent to deploy harder. Ask it to re-check the target, since the change most likely landed on a different deployment.
- Make your deployment configuration explicit in both .env.local and convex.json.
- Use the status tool if you have the official Convex MCP server installed.
- Compare npx convex env list fingerprints when you need to confirm which deployment you are on.
- Say 'read-only' explicitly when you want no changes at all for the session.
What people use it for
- Working on a personal dev deployment and several other Convex projects on the same laptop without mixing them up.
- Asking an agent to deploy a change to a preview or dev deployment with the target stated first.
- Auditing production data and logs through the MCP read tools without enabling production changes.
- Locking a debugging session to read-only so the agent cannot run mutations or imports.
- Investigating a deploy that seemed to do nothing by checking which deployment was actually changed.
Frequently asked questions
How do I install the convex-deploy-guard skill?
Download the ZIP from our page and unzip it. Put the skill folder in ~/.claude/skills/ for personal use, or in your project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
What do I need to use this skill?
You need a Convex project with CONVEX_DEPLOYMENT in .env.local and/or convex.json, plus the Convex CLI through npx convex. The official Convex MCP server is optional and only needed for the status tool and MCP flags.
Is the Convex Deployment Guard free to use?
The skill is published under the MIT licence. The source material does not mention pricing, so check the licence and your own Convex plan for any costs.
Does the skill deploy my code for me?
No. Per its own rules it is a safety discipline that other deploy skills call as a first step. It identifies and announces the target, and gates production actions behind explicit consent.
Can it stop an agent from changing production by accident?
It is designed to. The agent must classify and announce the target before deployment-affecting commands, and needs a fresh explicit yes for production actions in the current session. Read-only mode blocks deploys, env changes, mutations and imports.
Does the skill run scripts or use the network?
According to the source, it runs no scripts and uses no network. It only provides instructions to the agent. The commands it guards, such as npx convex deploy, are what can affect your deployments.
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 this skill if you work across several Convex deployments, or want a firm rule that an AI agent must name its target and get fresh consent before touching production. Pick something else if your project has no Convex backend, or if you want an agent to deploy to production without confirmation, since this skill is built to prevent that.
Download the skill