Convex Agent skill for Claude Code: add an in-app AI agent backend

Makes Claude add an in-app AI agent backend to a Convex app, with saved threads, message history, tool calls and vector search for RAG.

Installs: 38.4K; on skills.sh
Stars: 68; on GitHub
Updated: Oct 2026; last repo commit

Claude installs @convex-dev/agent and @convex-dev/ai-sdk-provider, adds the agent component to convex.config.ts, and defines the agent with languageModel: convexGateway("provider/model"). Threads and message history are stored in Convex, and model calls run in actions. For retrieval, it embeds your documents into a vector index and reads from it in a tool.

By default models are called through the Convex AI Gateway, where Convex holds the provider credentials, so you get no LLM key to manage. SKILL.md says that needs convex 1.45 or newer on a Convex Cloud deployment on a paid plan. The gateway does not serve embeddings yet, and free-plan, self-hosted or local setups call the provider SDK with a key you store in Convex env. The skill folder holds one file, SKILL.md.

Good for

Convex developers adding a chat or agent feature to their app
Teams that want conversation history stored in Convex
Apps that need retrieval over their own documents

Install convex-agent

Claude Code

Copy this prompt.

Install the convex-agent skill in Claude Code. Run this command:

npx skills add https://github.com/convex/agent-skills --skill convex-agent --skill convex-env

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

SKILL.md hands work to convex-env, so the first command installs it too. Convex's docs say the skills CLI installs skills into .agents/skills/ in your project. The "All Convex skills" command installs every skill in the repo, which has 33 skill folders. One of them, convex-improve-convex-plugin, is listed in the Convex docs as sending your coding session's transcript to the Convex team. Run this skill with /convex-agent in Claude Code or $convex-agent in Codex, or let the agent pick it when the task fits. SKILL.md says to store provider keys via an env step it calls the env micro power. The repo's closest match is convex-env, so the first command includes it.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

Add an AI agent / RAG backend (@convex-dev/agent) to the Convex app.

Sections in SKILL.md

Workflow
Rules

Key facts

Author: Convex (the vendor's own repo; Convex's docs list it among the skills it provides)
Repo: convex/agent-skills
License: Apache-2.0 (LICENSE file; the README says original content is Apache-2.0)
Installs on skills.sh: 38,383 (Nov 2, 2026)
GitHub stars: 68 (Nov 2, 2026)
Last commit to the repo: Oct 29, 2026
What installs: 1 file: SKILL.md
Needs: A Convex app; the gateway needs convex 1.45+ on a Convex Cloud paid plan, otherwise a provider API key
Works in: Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf, Codex (README lists how to invoke skills in each)
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Installs @convex-dev/agent and @convex-dev/ai-sdk-provider, adds the component
The agent component goes into convex.config.ts.
Runs code · Install the components
Sets tools, instructions and languageModel: convexGateway("provider/model")
The gateway needs no API key of your own, per SKILL.md.
Write · Define the agent
Creates threads, streams messages and saves history in Convex
Model calls run in actions, with "use node" if the SDK needs it.
Write · Threads and streaming
Embeds your docs into a vector index and retrieves them in a tool
SKILL.md says the gateway does not serve embeddings yet, so you store the embedding provider's key in Convex env.
Write · RAG with a vector index
Uses the provider SDK with a key in Convex env when the gateway is unavailable
That means a free plan, self-hosted or a local backend. The key is never exposed to the client.
Write · Provider key fallback

From the official docs

Permissions

Medium risk

Claude installs packages, edits your backend and may store a provider API key in Convex env, and model calls send chat content through the Convex AI Gateway. Keep keys out of client code and check billing before you enable it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Model calls leave your deployment
Prompts and chat content go through the Convex AI Gateway to a model provider. Do not send data you must keep private. github.com
It may need a paid plan and a provider key
The gateway needs convex 1.45+ on a paid Cloud plan. SKILL.md does not say how usage is billed. Embeddings and free-plan setups need your own provider key. github.com
It installs packages and edits config
It adds two packages and changes convex.config.ts. Review the diff and the commands before you approve them. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. It installs packages and writes backend code.
Talks to	Convex AI Gateway (model calls). Your embedding provider, when you add one
Sign-in and keys	Provider keys, when needed, go in Convex deployment env vars. SKILL.md says never to expose them client-side.
Scopes	Installs @convex-dev/agent and @convex-dev/ai-sdk-provider Edits convex.config.ts and adds agent, thread and vector-index code May store an embedding or provider API key in Convex env

Questions

How do I install convex-agent?

Use the install box above. The first command also installs convex-env, the repo skill that sets deployment env vars, because SKILL.md stores provider keys through an env step. Run it with /convex-agent in Claude Code or $convex-agent in Codex, or ask Claude to add an AI agent or chat feature to your Convex app.

Do I need an LLM API key?

Not for model calls through the Convex AI Gateway, where Convex holds the provider credentials. SKILL.md says the gateway needs convex 1.45 or newer on a Convex Cloud deployment on a paid plan. Embeddings for RAG, and free-plan, self-hosted or local setups, need a provider key stored in Convex env.

Who pays for the model calls?

SKILL.md says only that the gateway needs a paid plan and that Convex holds the provider credentials. It does not say how model usage is billed, so check Convex's pricing before you turn it on.

Why not write a messages table myself?

The convex-expert SKILL.md says to reach for @convex-dev/agent for any LLM or chat feature and never hand-roll it. The convex-design SKILL.md says not to hand-roll a messages table.

Is it safe?

It installs packages, edits convex.config.ts and your backend, and may store a provider API key in Convex env. Model calls go through the Convex AI Gateway by default, so prompts and chat content leave your deployment. Keep the key out of client code and review the diff.

Is it official?

Yes. It is in Convex's own agent-skills repo, and Convex's docs list it among the agent skills Convex provides.

Does it work in the Claude app?

The README and Convex docs name Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf and Codex. They do not name the Claude app, and this skill works on a local project, so we list no Claude app install.

Information

updated Nov 2, 2026

Repository: convex/agent-skills
Folder: skills/convex-agent

convex/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

convex/agent-skills README · github.com
Convex docs: Agent Skills · docs.convex.dev
convex-agent SKILL.md · github.com
convex-expert SKILL.md · github.com
convex-design SKILL.md · github.com