convex-expert

Writes and validates Convex backend functions, schemas, indexes, and queries.

9.4k|1.5k|Updated Jan 3, 2026
One-click install
npx skills add https://github.com/openclaw/clawhub --skill convex-expert
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: convex-expert
Source: https://github.com/openclaw/clawhub/tree/main/.agents/skills/convex-expert
Command: npx skills add https://github.com/openclaw/clawhub --skill convex-expert

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing Convex backend code requires strict conventions—object-form functions, validators, index-based reads, and correct generated imports—that generic AI assistants routinely get wrong, causing deploy failures and performance defects.

Core Features & Use Cases

  • Correct Function Authoring: Enforces object-form syntax with args and returns validators on every query, mutation, and action.
  • Index-First Data Access: Replaces unbounded .collect() and .filter() scans with .withIndex() queries and pagination for scalable reads.
  • Deploy Verification: Runs npx tsc --noEmit and convex dev pushes to catch validation and import errors before finishing.
  • Use Case: When adding a new messages table with a by-channel query, the skill defines the schema index, writes an internalQuery using withIndex and pagination, and verifies the deployment compiles cleanly.

Quick Start

Ask the agent to add a new Convex query with proper indexes and validators for a table in your convex/ directory.

Frequently Asked Questions about convex-expert

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a Convex query with proper indexing?

Define an index in convex/schema.ts with .index(...) and query it using .withIndex(...) instead of .filter(), which performs a full table scan. Add args and returns validators and use object-form syntax for every registered function.

What is the correct import for query and mutation in Convex?

Import query, mutation, action, and their internal variants from "./_generated/server", and api or internal from "./_generated/api". Importing query from "convex/server" or internal from "./_generated/server" causes hard deploy failures.

Can a Convex mutation call an external API?

No, mutations cannot fetch or perform external IO. All external calls belong in actions, which persist results by invoking internal mutations via ctx.runMutation.

Why does my Convex deploy fail with a validation error?

Deploys fail when functions lack args or returns validators, use wrong imports, or store invalid values like undefined. Run npx tsc --noEmit and push with convex dev to surface and fix every reported error.

How do I add a required field to an existing Convex table?

Never add a required field directly to a populated table. First add it as v.optional(...), backfill existing documents, then tighten the validator to required once all rows conform.