Best use case
Convex is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
## Overview
Teams using Convex should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/convex/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How Convex Compares
| Feature / Agent | Convex | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
## Overview
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Convex
## Overview
Convex is a reactive backend platform where database queries, mutations, and actions are defined in TypeScript and data automatically syncs to connected clients in real-time. It eliminates WebSocket code, polling, and cache invalidation, providing ACID transactions and optimistic updates out of the box.
## Instructions
- When defining schemas, use `defineSchema()` with `defineTable()` and typed validators (`v.string()`, `v.number()`, `v.id("tableName")`), and define indexes for all filtered and sorted queries.
- When writing functions, use queries for reads (automatically reactive), mutations for writes (transactional, triggers reactive updates), and actions for external API calls (non-transactional).
- When building React UIs, use `useQuery()` for reactive data subscriptions that auto-update, `useMutation()` for writes with optimistic updates, and `usePaginatedQuery()` for infinite scroll.
- When handling authentication, use `convex-auth` for built-in auth or integrate Clerk/Auth0, and validate user identity at the start of every mutation with `ctx.auth.getUserIdentity()`.
- When processing background work, use `ctx.scheduler.runAfter()` for delayed execution and cron jobs for recurring tasks instead of making mutations slow.
- When storing files, use `ctx.storage.store()` for upload and `ctx.storage.getUrl()` for serving URLs without S3 or CDN configuration.
- When implementing search, use full-text search indexes with `searchIndex()` or vector search with `vectorIndex()` for AI/RAG applications, with metadata filtering.
## Examples
### Example 1: Build a real-time chat application
**User request:** "Create a real-time chat app with Convex and React"
**Actions:**
1. Define `messages` table with schema, author reference, and timestamp index
2. Create a query function that returns messages sorted by timestamp
3. Create a mutation for sending messages with auth validation
4. Use `useQuery()` in React to subscribe to messages with automatic real-time updates
**Output:** A chat application where messages appear instantly for all connected users without WebSocket code.
### Example 2: Add full-text and vector search
**User request:** "Implement search across articles with both keyword and semantic search"
**Actions:**
1. Define search index on article body field with `searchIndex()`
2. Define vector index on embedding field with `vectorIndex()`
3. Create query functions for text search and vector similarity search
4. Combine metadata filtering with search for scoped results
**Output:** A dual search system supporting both keyword matching and semantic similarity queries.
## Guidelines
- Use schema validation in production: `defineSchema()` catches type errors at deploy time, not runtime.
- Define indexes for all filtered/sorted queries to ensure efficient data access.
- Use queries for reads, mutations for writes, actions for external APIs; never mix concerns.
- Keep mutations small and fast since they hold a database lock; move heavy processing to actions.
- Use `ctx.scheduler.runAfter()` for background work instead of making mutations slow.
- Validate user identity at the start of every mutation to prevent unauthorized writes.
- Use optimistic updates for interactive UIs; the client sees the change instantly while the server confirms.Related Skills
convex-setup-auth
Sets up Convex authentication with user management, identity mapping, and access control. Use this skill when adding login or signup to a Convex app, configuring Convex Auth, Clerk, WorkOS AuthKit, Auth0, or custom JWT providers, wiring auth.config.ts, protecting queries and mutations with ctx.auth.getUserIdentity(), creating a users table with identity mapping, or setting up role-based access control, even if the user just says "add auth" or "make it require login."
convex-quickstart
Initializes a new Convex project from scratch or adds Convex to an existing app. Use this skill when starting a new project with Convex, scaffolding with npm create convex@latest, adding Convex to an existing React, Next.js, Vue, Svelte, or other frontend, wiring up ConvexProvider, configuring environment variables for the deployment URL, or running npx convex dev for the first time, even if the user just says "set up Convex" or "add a backend."
convex-performance-audit
Audits and optimizes Convex application performance across hot-path reads, write contention, subscription cost, and function limits. Use this skill when a Convex feature is slow or expensive, npx convex insights shows high bytes or documents read, OCC conflict errors or mutation retries appear, subscriptions or UI updates are costly, functions hit execution or transaction limits, or the user mentions performance, latency, read amplification, or invalidation problems in a Convex app.
convex-migration-helper
Plans and executes safe Convex schema and data migrations using the widen-migrate-narrow workflow and the @convex-dev/migrations component. Use this skill when a deployment fails schema validation, existing documents need backfilling, fields need adding or removing or changing type, tables need splitting or merging, or a zero-downtime migration strategy is needed. Also use when the user mentions breaking schema changes, multi-deploy rollouts, or data transformations on existing Convex tables.
convex-create-component
Designs and builds Convex components with isolated tables, clear boundaries, and app-facing wrappers. Use this skill when creating a new Convex component, extracting reusable backend logic into a component, building a third-party integration that owns its own tables, packaging Convex functionality for reuse, or when the user mentions defineComponent, app.use, ComponentApi, ctx.runQuery/runMutation across component boundaries, or wants to separate concerns into isolated Convex modules.
Convex — Reactive Backend-as-a-Service
You are an expert in Convex, the reactive backend platform for TypeScript. You help developers build real-time applications with a built-in database, serverless functions, file storage, authentication, scheduled jobs, and automatic real-time sync to React/Next.js clients — replacing REST APIs, WebSocket servers, and database management with a single reactive backend that pushes updates to clients automatically.
convex-backend
Convex backend development guidelines. Use when writing Convex functions, schemas, queries, mutations, actions, or any backend code in a Convex project. Triggers on tasks involving Convex database operations, real-time subscriptions, file storage, or serverless functions.
Daily Logs
Record the user's daily activities, progress, decisions, and learnings in a structured, chronological format.
Socratic Method: The Dialectic Engine
This skill transforms Claude into a Socratic agent — a cognitive partner who guides
Sokratische Methode: Die Dialektik-Maschine
Dieser Skill verwandelt Claude in einen sokratischen Agenten — einen kognitiven Partner, der Nutzende durch systematisches Fragen zur Wissensentdeckung führt, anstatt direkt zu instruieren.
College Football Data (CFB)
Before writing queries, consult `references/api-reference.md` for endpoints, conference IDs, team IDs, and data shapes.
College Basketball Data (CBB)
Before writing queries, consult `references/api-reference.md` for endpoints, conference IDs, team IDs, and data shapes.