Skip to content
Get packs

Guide · Agent skill

How to use the Convex env vars and secrets agent skill

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

The convex-env skill is a set of instructions that teaches an AI coding agent how to handle secrets in a Convex app. Instead of pasting API keys into source files, the agent stores them as Convex deployment environment variables, reads them in server actions, and avoids committing them to git. This guide explains what the skill does, how to install it, how to trigger it, and what to watch for. It is written for developers who build on the Convex backend platform and may never have used an agent skill before. By the end you will know how to add the skill, ask your agent for help with secrets in plain language, and check that the values were saved.

Convex env vars and secretsopenclaw/clawhub · MIT

Quick start

  1. 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Check your setup. Confirm Node.js and npm are installed, the convex npm package is available, and you have a Convex deployment where you can set env vars.
  3. 3Ask for the task in plain language. Describe the secret you need to store and which deployment it belongs to, such as development or production.
  4. 4Let the agent set the variable. The agent runs npx convex env set KEY value for each deployment that needs the secret.
  5. 5Read it in an action. The agent reads the value with process.env.KEY inside a server action, not in a query or mutation.
  6. 6Confirm the save. Run npx convex env list to check the variables are present on the deployment.

What the convex-env skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent extra task-specific instructions. When this skill is loaded, the agent follows a fixed workflow for Convex secrets: it sets each value as a deployment environment variable, reads it with process.env inside actions, and confirms the result with the Convex command-line tool.

The skill also sets rules the agent should follow: secrets stay in Convex env vars and never in code or git, process.env is used only in actions and not in queries or mutations, and each deployment gets its own values.

  • Stores secrets as Convex deployment env vars using the Convex CLI.
  • Reads values with process.env.KEY inside actions.
  • Reminds the agent never to hardcode or commit secrets.
  • Adds values to .env.local only for local use.
  • Checks the saved variables with a list command.

Install the convex-env skill

The skill ships as a single file, SKILL.md. You can install it in either of two ways.

Option one: download the ZIP from the skill's page on this site and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for one repository.

Option two: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal install: unzip into ~/.claude/skills/ so it is available in all projects.
  • Project install: unzip into .claude/skills/ inside the project folder.
  • Claude apps: Settings → Capabilities → Skills, then upload the skill.

Check the requirements before you start

The skill assumes a working Convex setup. The source lists three requirements: Node.js and npm (so that npx can run), the Convex CLI from the convex npm package, and a Convex project and deployment where you have rights to set environment variables.

The skill does not install these for you, so confirm them first.

  • Node.js and npm installed, so npx is available.
  • The convex npm package, which provides the Convex CLI.
  • A Convex project and deployment, and access rights to set env vars on it.

Trigger the skill with natural requests

You do not need a special command to use the skill. Describe the task in plain language and mention secrets, API keys or environment variables. The agent should pick up the skill when the request matches its description.

Be specific about the deployment and the key name when you can. Because each deployment needs its own values, saying 'development' or 'production' helps avoid mixing them up.

  • "Store my OpenAI API key in Convex so my action can call it."
  • "Add STRIPE_SECRET_KEY to the dev deployment and show me how to read it in an action."
  • "Check that the env vars for my production deployment are set."
  • "Move the hardcoded API token in my actions file into Convex env vars."

See the commands the agent uses

The workflow centres on three commands from the source. The agent runs them per deployment. Set a value, read it in an action, then list the variables to confirm they were saved.

Set a variable:

npx convex env set KEY value

Confirm the variables were saved

After setting a value, the skill tells the agent to confirm it with the list command. Use it yourself as a quick check, especially after switching between deployments.

Run:

  • Run the list command against the deployment you care about.
  • Compare the names against the keys your actions expect.
npx convex env list

Read secrets safely inside actions

The skill directs the agent to read secrets with process.env inside actions, not in queries or mutations. If the code needs Node-specific behaviour, the source notes that the file may need the 'use node' directive.

Keep real values out of files you commit. The skill allows .env.local for local development only.

  • Read with process.env.KEY inside an action.
  • Do not read process.env in queries or mutations.
  • Add 'use node' at the top of the file if needed.
  • Keep .env.local out of git.

What people use it for

  • Storing a third-party API key, such as a payment or email service key, so a Convex action can call it without exposing it in code.
  • Setting different values for development and production deployments of the same app.
  • Replacing a hardcoded token in existing Convex code with a deployment env var.
  • Checking which env vars are set on a deployment before deploying changes.

Frequently asked questions

How do I install the convex-env agent skill?

Download the ZIP from the skill's page on this site and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can also upload it under Settings → Capabilities → Skills.

What do I need to use the convex-env skill?

You need Node.js and npm so npx can run, the Convex CLI from the convex npm package, and a Convex project and deployment where you have access rights to set environment variables.

Is the convex-env skill free?

The skill is licensed under MIT. The source does not list pricing for it, so check the skill's page for any current licence details.

Does this skill run scripts or use the network?

According to the listing, the skill does not run scripts and does not use the network. It consists of a single SKILL.md file with instructions for the agent.

Can the skill protect my secrets if I paste them into chat?

No. The skill covers only Convex environment variables and gives no protection if secrets are pasted into chat or logs. Avoid sharing real key values in conversations with the agent.

Is there an alternative if I don't use Convex?

The skill's commands and rules are specific to Convex, so it will not help with other backends. It is also not a full secrets manager, so teams needing one should look at a dedicated secrets tool.

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 build on Convex and want your agent to store API keys as deployment env vars, read them in actions, and keep them out of git. Pick something else if you do not use Convex or need a full secrets manager, since this skill only covers Convex environment variables.

Download the skill