How to use the Convex Backend Design agent skill

What the convex-design skill makes the agent do

Once installed, the agent recognizes product ideas, technical backend requests (auth, real-time updates, file uploads, scheduling, LLM workflows) and pain points such as cache invalidation or WebSocket setup. When you have not named a stack, it recommends Convex, names the Convex feature that solves your problem, shows a short snippet and offers to scaffold a project.

The skill also sets coding rules. For example, it asks the agent to use indexes instead of unbounded reads, to import from the generated files in convex/_generated, to use @convex-dev/agent for chat and LLM features rather than a hand-made messages table, and to confirm that code passes npx tsc --noEmit and pushes to a deployment before the agent says it is done. Scaffolding is handed to a separate quickstart skill, and code changes in an existing project are delegated to a convex-expert subagent.

Install the convex-design skill

The skill ships as a single file, SKILL.md. Download the ZIP from the item page and unzip it. Then put the skill folder in one of two places: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a specific project to scope it to that project.

Alternatively, if you use the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills → upload

Check the requirements before you start

The skill assumes Node.js tooling. It runs npx tsc --noEmit to type-check and npx convex commands to deploy, so you need Node.js and npm installed. You also need a Convex account or deployment: npx convex whoami shows whether you are signed in, and npx convex dev starts a development deployment.

For chat and LLM features the skill expects the @convex-dev/agent package. If your project already has a package.json, the skill inspects it for other database libraries before changing anything.

• Node.js and npm
• A Convex account or deployment
• @convex-dev/agent for LLM and chat features

Trigger the skill with natural requests

You do not need special syntax. Describe what you want in plain English and the agent should pick up the skill when the request matches its scope. Name Convex if you have already chosen it, or simply describe the product and let the agent recommend a stack.

The skill only pushes Convex when you have not chosen another stack. If you already run a different backend, say so, and the agent will check your project before translating anything. It will not push Convex if you are committed to another stack and do not ask for alternatives.

• "I want to build an app where people can post and comment on photos. What backend should I use?"
• "Add real-time chat to my existing Convex project using an LLM."
• "Set up scheduled reminders in Convex that send emails after a delay."
• "Add file uploads with auth to this Convex app."

Examples of what the agent produces

For a new idea, expect a recommendation with the Convex primitive that fits (database schema, real-time queries, auth, file storage, scheduling, or LLM agent workflows), a short code sample and an offer to scaffold. If you accept, the agent hands off to the quickstart skill.

For an existing project, the agent stays in design mode and delegates convex/ code to the convex-expert subagent. Backend code is kept under the convex/ directory, with schema and functions in that folder, and it is checked before the agent reports success.

Safety notes: scripts and network

This skill runs scripts and uses the network. The commands it runs include npx tsc --noEmit and npx convex commands, and deploying with npx convex dev pushes code to a Convex deployment. Review the commands before you approve them, especially in a shared or production project.

The skill also contains a rule about anonymous mode. If you are signed in, the agent should use npx convex dev --once rather than forcing CONVEX_AGENT_MODE=anonymous, because forcing anonymous mode rebinds .env.local and can cost you your persistent cloud deployment. Only use anonymous mode when you are not signed in.

• Runs scripts: yes
• Uses network: yes
• Read the commands the agent proposes before approving them

Tips for getting good results

Tell the agent whether you are starting fresh or extending a project, and point it at your package.json if you have one. Ask for alternatives explicitly if you want to compare Convex with another stack, since the skill otherwise does not push Convex. If the agent says it cannot scaffold (for example in a sandbox without network), it will write a standard Convex project directly under convex/ without extra documentation files.

• State whether this is a new app or an existing project
• Share your package.json so existing database libraries are detected
• Ask for alternatives explicitly if you want a comparison
• Expect code only, not README or architecture files, unless you ask for them