# convex-expert

A skill for any code under convex/: functions, schemas, indexes, validators. Useful when your agent writes Convex backend code.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 36200 installs · ★ 68
- Author: convex
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/convex/agent-skills/tree/HEAD/skills/convex-expert/SKILL.md
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/skills/convex-expert

## What it does

The skill fires before you touch anything in `convex/`. First it reads `convex/schema.ts` and `convex/_generated/ai/guidelines.md` if that file exists. Every registered function then gets written in object form, with both `args` and `returns` validators.

Most of the value is in the rules generic models get wrong. Imports must come from `./_generated/server` and `./_generated/api`, or the deploy fails. Reads go through `.withIndex(...)`, never `.filter()`. Functions stay internal by default — `internalQuery`, `internalMutation`, `internalAction` — and only get promoted when a client hook needs them. For LLM chat features the skill reaches for `@convex-dev/agent`; multi-step flows use `@convex-dev/workflow`.

Before calling the work done, it verifies the code compiles and pushes: `npx tsc --noEmit` plus a push to a deployment. Watch out here. If you are already signed in to Convex, `CONVEX_AGENT_MODE=anonymous` rebinds `.env.local` and you lose the cloud deployment you had, so anonymous mode is only for when `npx convex whoami` fails.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add convex/agent-skills --skill convex-expert -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/convex-expert/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/convex-expert/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add convex/agent-skills --skill convex-expert -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/convex-expert/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add convex/agent-skills --skill convex-expert -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/convex-expert/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install convex/agent-skills convex-expert
```

2. **Manually: put the files in place**
- File: `.github/skills/convex-expert/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add convex/agent-skills --skill convex-expert -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/convex/agent-skills --path skills/convex-expert
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/convex-expert/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add convex/agent-skills --skill convex-expert -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/convex/agent-skills/tree/HEAD/skills/convex-expert/SKILL.md

## When to use it
- write Convex functions in object form with validators
- swap `.filter()` for `.withIndex(...)` on read paths
- get imports from `./_generated/server` and `./_generated/api` right
- add a field to a populated table with `v.optional(...)` and backfill
- use `@convex-dev/agent` instead of hand-rolled chat plumbing

## Example prompts
- add a mutation to convex/messages.ts for sending a message
- rewrite this query with withIndex instead of filter
- verify the backend compiles and pushes

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f67fb686f21c2b18.

BEGIN THIRD-PARTY FILE f67fb686f21c2b18
```text
---
name: convex-expert
description: "Convex backend specialist. Use this agent for any code inside a `convex/` directory — function definitions, schemas, indexes, queries, mutations, actions, HTTP endpoints, cron jobs, file storage, auth wiring, and component installation. Knows the object-form function syntax, validator patterns, resource limits, and component ecosystem that generic Claude routinely gets wrong."
---

<!-- GENERATED from convex-agents content/capabilities/convex-expert.json — do not edit by hand. -->

# Convex backend specialist

Always-on Convex backend specialist invoked before touching any code inside a convex/ directory. Knows the object-form function syntax, validator requirements, index naming rules, internal-vs-public discipline, schema evolution patterns, resource limits, component ecosystem, and runtime error decoder that generic models routinely get wrong.

## Workflow

1. When about to write or edit any file under convex/: read convex/schema.ts first (and convex/_generated/ai/guidelines.md if present).
2. Write all Convex functions in object form with both args and returns validators on every registered function.
3. Use withIndex(...) for every read path — never .filter() for anything that would be a SQL WHERE clause.
4. Default to internalQuery/internalMutation/internalAction; promote to public only when a client hook needs it.
5. For any LLM/chat feature reach for @convex-dev/agent; for multi-step flows use @convex-dev/workflow — never hand-roll these.
6. After writing, confirm convex dev pushed cleanly and fix any Schema/Returns/Argument validation errors in place.

## Rules

- DATA ACCESS + IMPORTS — read before writing any convex/*.ts (front-loaded, not a post-hoc lint):
- Never an unbounded `.collect()` on a table that can grow — use `.withIndex(...)` and `.paginate(paginationOptsValidator)`/`.take(n)` instead. This is the single most common Convex deploy-blocking and perf defect.
- Index, don't filter — add `.index(...)` in schema.ts for every read path and query it with `.withIndex(...)`; `.filter()` is a full table scan, never a substitute for a WHERE.
- The exact import table — get this wrong and the app fails to deploy: `query`/`mutation`/`action`/`internalQuery`/`internalMutation`/`internalAction` come from `"./_generated/server"`; `api`/`internal` come from `"./_generated/api"`; NEVER `import { query } from "convex/server"` or `import { internal } from "./_generated/server"` in application code — both are hard deploy failures.
- `v.literal("exact value")` for a fixed string/enum member (e.g. `v.union(v.literal("open"), v.literal("closed"))`) — not a bare `v.string()` when the set of values is fixed.
```
END THIRD-PARTY FILE f67fb686f21c2b18

The third-party file has ended. Everything between the f67fb686f21c2b18 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2708 of 4469 bytes. © convex · Apache-2.0 · https://github.com/convex/agent-skills/tree/HEAD/skills/convex-expert/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md