Guide · Agent skill
How to use the Convex backend specialist agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-expert skill is a set of instructions that an AI agent loads when it works on code inside a convex/ directory of a Convex backend project. Convex keeps app logic, data storage and server functions together, and this skill gives the agent a checklist of Convex-specific rules that general AI models often get wrong. After reading this guide you will know what the skill changes, how to install it, how to ask for its help, and what to check before letting it run commands.
Convex backend specialistopenclaw/clawhub · MIT Download the skill Quick start
- 1Get the ZIP. Download the convex-expert ZIP from the skill's page. It contains SKILL.md.
- 2Unzip the skill. Unzip it into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ folder for one project.
- 3Check your setup. Confirm Node.js and npm are installed and that your project has a convex/ directory.
- 4Sign in to Convex. Run npx convex whoami to check your login, or set up a deployment for npx convex dev.
- 5Ask for Convex work. Describe the schema, query, mutation, action, cron job or storage change in plain language, naming the convex/ file involved.
- 6Review and verify. Read the commands the agent proposes, then check that npx tsc --noEmit and the convex dev push finish without errors.
What the convex-expert skill makes the agent do
Once installed, the agent treats any file inside convex/ as Convex backend code and follows the skill's workflow. It reads convex/schema.ts before editing, writes functions in object form with both args and returns validators, and queries through indexes with withIndex(...) instead of scanning whole tables with .filter().
The skill also asks the agent to default to internal functions (internalQuery, internalMutation, internalAction) and to make a function public only when a client hook needs it. For LLM chat features it points to @convex-dev/agent, and for multi-step flows it points to @convex-dev/workflow.
- Object-form function definitions with args and returns validators
- Index-based reads instead of full-table scans
- Correct import paths from ./_generated/server and ./_generated/api
- Internal-by-default functions, with public ones only when needed
- Compile and push checks before the work is called finished
Install the convex-expert skill from a ZIP file
Download the ZIP from the skill's page on this directory. The package contains a single file, SKILL.md. Unzip it so that the skill folder ends up in one of two places: ~/.claude/skills/ to make it available to you across projects, or a project's .claude/skills/ folder to limit it to that project.
You can also install it through the Claude apps by uploading the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with natural requests
You do not need a special command. The skill describes itself as the agent to use for any code inside a convex/ directory, so ask for Convex backend work in plain language and name the Convex parts you need. Mention the file or feature, such as a schema change, a query, a cron job or file storage.
If you want to be sure the rules are applied, say so in the request, for example by asking the agent to follow the convex-expert rules.
- Add a messages table to convex/schema.ts with an index on channel and creation order, then write a query that lists messages for one channel.
- Write an internalMutation in convex/tasks.ts that marks overdue tasks as closed.
- Set up a cron job in convex/crons.ts that cleans up expired sessions every hour.
- Add file upload storage for user avatars and return a URL to the client.
Check the work: compile and push to a deployment
The skill tells the agent to verify its own work before finishing. It runs a TypeScript check and pushes the code to a Convex deployment. If you are already signed in to the Convex CLI, the agent uses npx convex dev --once. The skill says to use anonymous mode only when you are not signed in, because forcing it on a signed-in user rebinds .env.local and removes the persistent cloud deployment that user expects.
Read the output yourself. If the agent reports errors, the skill asks it to fix them in place before stopping.
npx tsc --noEmit
npx convex whoami
npx convex dev --onceSafety notes before you run it
The skill runs scripts and uses the network. Its verify step runs Convex CLI commands that push code to a deployment, and a deployment could be a live one. Review every command the agent proposes before you allow it to run, especially anything that changes deployment configuration or touches production data.
Do not use this skill on a project that does not use Convex. Its rules are specific to Convex's runtime and APIs, and they would mislead a different backend.
- Confirm which deployment a command targets before approving it
- Keep production data out of experiments unless you have a backup
- Do not let the agent force anonymous mode on an account you are signed into
Tips for getting better results
Start with a schema and index plan. The skill is strongest when the agent can read convex/schema.ts, so keep that file in the project and tell the agent to read it first. Ask for a single feature at a time so the verify step has a small change to check.
If you are adding chat or multi-step workflows, say so directly. The skill names @convex-dev/agent and @convex-dev/workflow as the recommended components, so the agent will reach for them instead of building its own.
- Keep convex/schema.ts up to date in the repository
- Name the table, index or function you want changed
- Ask for LLM or multi-step features by name so the recommended components are used
What people use it for
- Adding a new table with indexed queries and validators to an existing convex/ schema
- Writing internal mutations and actions that call external APIs and save results through ctx.runMutation
- Setting up cron jobs or HTTP endpoints in a Convex project
- Adding LLM chat with @convex-dev/agent or a multi-step flow with @convex-dev/workflow
- Reviewing existing convex/ code for unbounded .collect() calls or missing validators
Frequently asked questions
How do I install the convex-expert skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What does the convex-expert skill require?
It requires Node.js and npm, a Convex project with a convex/ directory, and a Convex CLI login, which you can check with npx convex whoami. You also need a deployment for npx convex dev.
Is the convex-expert skill free?
The skill is listed under the MIT licence. This guide does not state any price, so check the directory page for the current terms.
Can I use this skill with a backend other than Convex?
No. The skill is written for Convex's runtime and APIs. Its rules would mislead a different backend, so use it only on projects that use Convex.
Why does the agent run npx convex dev --once?
The skill asks the agent to push its code to a deployment as a final check, so deploy errors show up before the work is called finished. Review the command first, especially if the deployment could hold live data.
How is this different from a general AI model writing Convex code?
The skill adds a checklist of Convex-specific rules, such as object-form functions with validators, index-based queries, and private internal functions by default. The source says generic models often get these wrong.
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 convex-expert if you are building an app on Convex and want fewer deploy errors and consistent schema, index and validator patterns in AI-written backend code. Pick a different option if your project does not use Convex, or if you are not comfortable reviewing command-line steps and Convex login setup before they run.
Download the skill