Convex Deploy Guard skill for Claude Code: stop commands hitting the wrong deployment

Makes Claude name which Convex deployment a command will hit, say it out loud, and ask again before touching production.

Installs: 38.5K; on skills.sh
Stars: 68; on GitHub
Updated: Oct 2026; last repo commit

Before any command that affects a deployment, Claude reads CONVEX_DEPLOYMENT in .env.local, convex.json and whether CONVEX_DEPLOY_KEY is set, or calls the Convex MCP status tool. It sorts the target into local-anonymous, dev, preview or prod, and announces it in one line before it acts.

Production needs a fresh, explicit yes in the current session for each action: npx convex deploy aimed at prod, npx convex run --prod, env set on prod, snapshot import or export on prod, or starting the MCP with prod access. Say "read-only" and Claude must not deploy, set or remove env vars, run functions or import data for the rest of the session. The skill folder holds one file, SKILL.md.

Good for

Convex developers with dev, preview and prod deployments on one machine
Teams whose assistant can run npx convex commands
Anyone who wants a read-only session on a live backend

Install convex-deploy-guard

Claude Code

Copy this prompt.

Install the convex-deploy-guard skill in Claude Code. Run this command:

npx skills add https://github.com/convex/agent-skills --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.

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-deploy-guard in Claude Code or $convex-deploy-guard in Codex, or let the agent pick it when the task fits. This skill can call the official Convex MCP status tool, which is optional here and not part of the skills. To use it, add the server command to your client's MCP settings; the Convex docs also describe an official plugin that starts it for you.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Classify + announce the target Convex deployment before any deployment-affecting command; fresh explicit consent for prod actions; session read-only mode.

Sections in SKILL.md

Workflow
Rules

Key facts

Author: Convex (the vendor's own repo; Convex's docs list it among the skills it provides)
Repo: convex/agent-skills
License: Apache-2.0 (LICENSE file; the README says original content is Apache-2.0)
Installs on skills.sh: 38,525 (Nov 2, 2026)
GitHub stars: 68 (Nov 2, 2026)
Last commit to the repo: Oct 29, 2026
What installs: 1 file: SKILL.md, with no scripts or hooks
Needs: Reads .env.local and convex.json; the Convex MCP is optional for the status check
Works in: Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf, Codex (README lists how to invoke skills in each)
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Reads CONVEX_DEPLOYMENT, convex.json and CONVEX_DEPLOY_KEY, or the MCP status tool
Claude classifies the target as local-anonymous, dev, preview or prod. If two sources disagree it resolves that first.
Files · Identify the target
States the target in one line before any deployment-affecting command
The announcement looks like target: dev (name, personal dev). Claude never runs the command in the same breath as finding the target.
Announce first
Needs an explicit yes in this session for each prod action
This covers deploy to prod, run --prod, env set on prod, snapshot import or export on prod, and starting the MCP with prod access. An earlier yes, or one for another target, does not carry.
Fresh yes for prod
Starts the Convex MCP on a non-prod deployment and keeps the two prod flags apart
--cautiously-allow-production-pii is for read-only prod audits. --dangerously-enable-production-deployments allows changes and stays off unless you asked to change prod.
Runs code · MCP safety defaults
After you say read-only, no deploys, env changes, runs or imports
Claude starts the MCP with --disable-tools run,envSet,envRemove for the rest of the session.
Read-only session mode
If a deploy did nothing, re-checks the target instead of deploying again
SKILL.md says the deploy almost certainly landed on a different deployment than the one being observed.
Wrong-deployment diagnosis

From the official docs

Permissions

Low risk

The skill is a set of instructions, not a lock, and agent commands still use your own Convex credentials. Use a deploy key limited to one deployment if you need a hard limit.

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

It is instructions, not a technical block
The skill bundles no scripts or hooks. Claude follows its steps; nothing in the skill enforces them. github.com
Agent commands use your full Convex credentials
The Convex MCP docs say npx convex commands an agent runs get the full authorization of your credentials unless you use a scoped deploy key. Use a deploy key limited to one deployment for a hard limit. docs.convex.dev
The docs list two names for the deployment flag
SKILL.md uses --deployment dev. The Convex CLI reference for npx convex mcp start lists --deployment <deployment>, and the Convex MCP server page lists --deployment-name. Check the flag your version accepts. docs.convex.dev

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	Say "read-only" and SKILL.md bars deploys, env changes, runs and imports for the session. SKILL.md has Claude start the MCP with --disable-tools run,envSet,envRemove.
Scopes	Reads .env.local and convex.json, and checks whether CONVEX_DEPLOY_KEY is set Can call the Convex MCP status tool

Questions

How do I install convex-deploy-guard?

Use the install box above. SKILL.md says other skills (ship, env, migrate and seed) run it as their step 0. Run it with /convex-deploy-guard in Claude Code or $convex-deploy-guard in Codex.

Does it actually block a production command?

It is a set of instructions Claude follows. The skill bundles no scripts or hooks, so nothing in it enforces the rule. The Convex MCP docs add that npx convex commands an agent runs use your full credentials unless you use a scoped deploy key.

What do the two production flags do?

Per the Convex MCP docs, --cautiously-allow-production-pii lets agents read data, logs and queries on prod. --dangerously-enable-production-deployments also lets them read environment variables and run functions or change env vars. SKILL.md keeps them split so looking at prod never silently allows changes.

Which flag selects a non-prod deployment?

SKILL.md writes the MCP start option as --deployment dev. The Convex CLI reference for npx convex mcp start lists --deployment <deployment>, which accepts a deployment name, a reference such as dev or prod, or local. The Convex MCP server page instead lists --deployment-name <name>, --preview-name and --prod. Both flag names appear in Convex docs. Our advice: check the flags your Convex version accepts.

Is it safe?

It tells Claude to name the target and ask before production actions. It bundles no scripts or hooks, so it relies on Claude following it. Our advice: pair it with a scoped deploy key if you need a hard limit, since agent commands run with your own credentials otherwise.

Is it official?

Yes. It is in Convex's own agent-skills repo, and Convex's docs list it among the agent skills Convex provides.

Does it work in the Claude app?

The README and Convex docs name Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf and Codex. They do not name the Claude app, and this skill works on a local project, so we list no Claude app install.

Information

updated Nov 2, 2026

Repository: convex/agent-skills
Folder: skills/convex-deploy-guard

convex/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

convex/agent-skills README · github.com
Convex docs: Agent Skills · docs.convex.dev
Convex docs: MCP server · docs.convex.dev
convex-deploy-guard SKILL.md · github.com
npx convex mcp reference · docs.convex.dev