AutoGineer
Generated banner for Convex Deploy Guard
Generated logo for Convex Deploy Guard

Convex Deploy Guard

ConvexOfficialPublished by Convex

  • Skill
  • Guidelines
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

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

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The convex-deploy-guard provides a structured safety protocol to prevent accidental deployments or mutations to the wrong environment. By enforcing a strict identify-announce-act sequence, it ensures that every deployment-affecting command is preceded by a clear declaration of the target environment. It introduces mandatory, session-specific consent for production actions and establishes clear boundaries for read-only versus mutating operations, ensuring that production access is never granted by default.

What it does

  • Identifies the target deployment by checking environment variables and configuration files.
  • Requires an explicit announcement of the target environment before any deployment command.
  • Enforces fresh, per-action consent for all production-impacting operations.
  • Separates read-only production access from mutating production access.
  • Maintains a strict read-only session mode when requested by the user.
  • Provides diagnostic steps for when a deployment appears to have no effect.

When to use it

  • Before running any command that modifies a Convex deployment.
  • When working across multiple environments like dev, preview, and production.
  • When you need to ensure production changes are intentional and verified.
  • When you want to audit production data without the risk of accidental mutations.

Advantages

  • Reduces the risk of human error when managing multiple deployment targets.
  • Ensures production changes are always deliberate and documented in the session.
  • Prevents accidental mutations by defaulting to safe, non-prod configurations.
  • Provides a clear diagnostic path when deployment outcomes are unexpected.

Usage examples

“Deploy my current changes to the production environment.”
The agent identifies the target as production, states the specific changes to be made, and requests your explicit confirmation before proceeding.
“I need to audit production logs, but keep it read-only.”
The agent initiates a read-only session, disables all mutation tools, and confirms that only read-access is enabled for the production environment.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/convex/convex-deploy-guard/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip convex-deploy-guard.zip -d .agents/skills

Documentation by Convex

<!-- GENERATED from convex-agents content/capabilities/deploy-guard.json — do not edit by hand. -->

Deployment target guard

Deployments are not interchangeable, and most incidents start with a command aimed at the wrong one. Every Convex project has several (personal dev, preview, prod — often across multiple projects on one machine). This guard is the standing discipline: identify, announce, then act — and treat prod as consent-gated, per action, per session.

Workflow

  1. IDENTIFY before you act: read CONVEX_DEPLOYMENT in .env.local, convex.json, and whether CONVEX_DEPLOY_KEY is set; or call the official Convex MCP status tool. Classify the target: local-anonymous | dev | preview | prod. If two sources disagree, resolve before proceeding.

  2. ANNOUNCE in one line before any deployment-affecting command: target: dev (joyful-capybara-123, personal dev). Never run the command in the same breath as discovering the target — announce first.

  3. PROD needs a FRESH explicit yes: before npx convex deploy (when it resolves to prod), npx convex run --prod, env set on prod, snapshot import/export on prod, or starting the MCP with prod access — state exactly what will change on which deployment and get an explicit yes in THIS session. A yes given earlier, or for a different target, does not carry.

  4. MCP safety defaults: start the official MCP scoped non-prod (--deployment dev). The two prod flags are DIFFERENT risk levels — keep them split: a read-only prod audit (advisor/insights reading data/logs/insights) passes ONLY --cautiously-allow-production-pii (read tools); --dangerously-enable-production-deployments (which enables MUTATING prod tools) stays OFF unless the user explicitly asked to CHANGE prod this session. Never pair them by default — 'look at prod' must not silently grant 'mutate prod'.

  5. READ-ONLY session mode: when the user says 'read-only' / 'don't change anything', honor it absolutely for the rest of the session — no deploy, no env set/remove, no mutations via run, no imports; start the MCP with --disable-tools run,envSet,envRemove.

  6. Wrong-deployment diagnosis: when a deploy 'didn't change anything', do NOT re-deploy harder. Re-run step 1 — the deploy almost certainly landed on a different deployment than the one being observed.

  7. Ambiguity = stop: if you cannot determine which deployment a command will hit, find out (status tool) — never guess.

Rules

  • Classify and announce the target BEFORE every deployment-affecting command — identification and action are two separate steps.

  • Prod consent is per-action, per-target, per-session: state what changes where, get a fresh explicit yes.

  • Keep the two prod MCP flags split by risk: --cautiously-allow-production-pii (read-only) for an audit; --dangerously-enable-production-deployments (mutating) only when the user explicitly asks to change prod. Both are user-spoken-only; default every MCP start to a non-prod deployment selector.

  • Read-only mode, once requested, is absolute for the session — including 'harmless' mutations.

  • A deploy that seemed to do nothing means the WRONG deployment changed — diagnose the target, don't re-run.

  • This guard composes: ship, env, migrate, and seed run it as their step 0; it is not itself a deploy tool.

Files

SKILL.md

<!-- GENERATED from convex-agents content/capabilities/deploy-guard.json — do not edit by hand. -->

Deployment target guard

Deployments are not interchangeable, and most incidents start with a command aimed at the wrong one. Every Convex project has several (personal dev, preview, prod — often across multiple projects on one machine). This guard is the standing discipline: identify, announce, then act — and treat prod as consent-gated, per action, per session.

Workflow

  1. IDENTIFY before you act: read CONVEX_DEPLOYMENT in .env.local, convex.json, and whether CONVEX_DEPLOY_KEY is set; or call the official Convex MCP status tool. Classify the target: local-anonymous | dev | preview | prod. If two sources disagree, resolve before proceeding.

  2. ANNOUNCE in one line before any deployment-affecting command: target: dev (joyful-capybara-123, personal dev). Never run the command in the same breath as discovering the target — announce first.

  3. PROD needs a FRESH explicit yes: before npx convex deploy (when it resolves to prod), npx convex run --prod, env set on prod, snapshot import/export on prod, or starting the MCP with prod access — state exactly what will change on which deployment and get an explicit yes in THIS session. A yes given earlier, or for a different target, does not carry.

  4. MCP safety defaults: start the official MCP scoped non-prod (--deployment dev). The two prod flags are DIFFERENT risk levels — keep them split: a read-only prod audit (advisor/insights reading data/logs/insights) passes ONLY --cautiously-allow-production-pii (read tools); --dangerously-enable-production-deployments (which enables MUTATING prod tools) stays OFF unless the user explicitly asked to CHANGE prod this session. Never pair them by default — 'look at prod' must not silently grant 'mutate prod'.

  5. READ-ONLY session mode: when the user says 'read-only' / 'don't change anything', honor it absolutely for the rest of the session — no deploy, no env set/remove, no mutations via run, no imports; start the MCP with --disable-tools run,envSet,envRemove.

  6. Wrong-deployment diagnosis: when a deploy 'didn't change anything', do NOT re-deploy harder. Re-run step 1 — the deploy almost certainly landed on a different deployment than the one being observed.

  7. Ambiguity = stop: if you cannot determine which deployment a command will hit, find out (status tool) — never guess.

Rules

  • Classify and announce the target BEFORE every deployment-affecting command — identification and action are two separate steps.

  • Prod consent is per-action, per-target, per-session: state what changes where, get a fresh explicit yes.

  • Keep the two prod MCP flags split by risk: --cautiously-allow-production-pii (read-only) for an audit; --dangerously-enable-production-deployments (mutating) only when the user explicitly asks to change prod. Both are user-spoken-only; default every MCP start to a non-prod deployment selector.

  • Read-only mode, once requested, is absolute for the session — including 'harmless' mutations.

  • A deploy that seemed to do nothing means the WRONG deployment changed — diagnose the target, don't re-run.

  • This guard composes: ship, env, migrate, and seed run it as their step 0; it is not itself a deploy tool.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Convex
Publisher
Convex (Official)
Source
convex/agent-skills · skills/convex-deploy-guard · commit f60629d
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Convex.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download convex-deploy-guard.zip