How to use the Convex AI agent backend agent skill

What is an agent skill, and what does convex-agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. The convex-agent skill covers one task: adding an AI agent / RAG backend to a Convex application using the @convex-dev/agent package.

According to the skill, the setup gives you durable threads, message history, tool calls, and vector search for retrieval-augmented generation (RAG). Model calls go through the Convex AI Gateway by default, so Convex holds the provider credentials and you do not need to obtain, store, or rotate an LLM key in most cases.

• Installs @convex-dev/agent and @convex-dev/ai-sdk-provider and adds the agent component to convex.config.ts
• Defines an agent with tools and instructions using convexGateway("provider/model")
• Creates threads, streams messages, and persists history in Convex
• Embeds documents into a vector index and retrieves them inside a tool for RAG
• Falls back to a provider key stored in Convex env only where the gateway is unavailable

What you need before installing

The skill lists these requirements. Check them before you start, because the setup assumes a Convex project and deployment.

The skill is for Convex only. Its steps assume Convex functions, config files, and deployments, so it does not help with other backends.

• Convex 1.45 or later
• A Convex Cloud deployment on a paid plan, which is needed for the AI Gateway
• npm packages @convex-dev/agent and @convex-dev/ai-sdk-provider
• An embedding provider API key, only if you use RAG embeddings (stored in Convex env)
• A provider API key only where the gateway is unavailable, such as the free plan, self-hosted, or local setups

How do you install the convex-agent skill?

Download the ZIP from this page and unzip it. The skill folder contains a single file, SKILL.md. Put the unzipped folder in one of these locations:

• Personal skills: ~/.claude/skills/
• Project skills: .claude/skills/ inside your project folder
• Claude apps: upload the skill under Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in plain language that matches the skill's purpose, such as adding an AI assistant or chat feature to a Convex app, or adding document search over your own content. The agent decides whether the skill applies, so mention Convex and the feature you want to make the match clear.

• "Add an AI chat assistant to my Convex app that saves conversation history."
• "Set up RAG over the documents in my Convex project so the chatbot can answer from them."
• "Add a tool-calling AI agent backend to this Convex app using @convex-dev/agent."

What does the agent do step by step?

The skill's workflow runs in a fixed order. You can review each step as the agent works through it.

• Install @convex-dev/agent and @convex-dev/ai-sdk-provider, then register the agent component in convex.config.ts.
• Define the agent with its tools and instructions, using the gateway model by default.
• Create threads and stream messages, with history persisted in Convex.
• For RAG, embed documents into a vector index and retrieve them in a tool. The gateway does not serve embeddings yet, so the embedding provider's key is stored via the env micro power.
• Use a provider key only if the gateway is unavailable.

What are the safety rules and what does the skill run?

This skill runs scripts and uses the network. The setup installs packages and adds backend functions to your project, so review the changes before deploying. The skill's rules say to never expose a provider API key client-side and to keep any needed key in Convex env via the env micro power. Model calls should run in actions, using 'use node' if the SDK needs it.

If your project must avoid new dependencies or server-side code execution, do not use this skill.

• Keep provider keys out of client code.
• Run model calls in Convex actions.
• Store threads and messages in Convex for durability and reactivity.
• Review installed packages and new backend functions before deploying.

Tips for a smoother setup

Confirm your Convex version and plan first, since the gateway needs Convex 1.45 or later on a paid Convex Cloud deployment. If you are on the free plan, self-hosted, or running locally, plan for a provider key stored in Convex env and the extra key-handling responsibility that comes with it.

• Check the Convex version and deployment type before asking for the setup.
• Name the feature you need (chat, tools, or RAG) so the agent loads the right steps.
• Expect to provide an embedding provider key if you need RAG, because the gateway does not serve embeddings yet.