# Convex Backend

Convex backend development guidelines.

- Repository: https://github.com/CloudAI-X/claude-workflow-v2 (1421 stars)
- Category: Data and ML
- License: MIT
- Last updated: 2026-10-06
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -g -a claude-code -y`
Codex: `npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -g -a codex -y`
Cursor: `npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -g -a cursor -y`
Gemini CLI: `npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add CloudAI-X/claude-workflow-v2`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Convex Backend Guidelines

### When to Load

- **Trigger**: Convex-specific development, writing Convex functions, schemas, queries, mutations, actions, or real-time subscriptions
- **Skip**: Project does not use Convex as its backend

Comprehensive guide for building Convex backends with TypeScript. Covers function syntax, validators, schemas, queries, mutations, actions, scheduling, and file storage.

## When to Apply

Reference these guidelines when:

- Writing new Convex functions (queries, mutations, actions)
- Defining database schemas and validators
- Implementing real-time data fetching
- Setting up cron jobs or scheduled functions
- Working with file storage
- Designing API structure

## Rule Categories

| Category          | Impact   | Description                                   |
| ----------------- | -------- | --------------------------------------------- |
| Function Syntax   | CRITICAL | New function syntax with args/returns/handler |
| Validators        | CRITICAL | Type-safe argument and return validation      |
| Schema Design     | HIGH     | Table definitions, indexes, system fields     |
| Query Patterns    | HIGH     | Efficient data fetching with indexes          |
| Mutation Patterns | MEDIUM   | Database writes, patch vs replace             |
| Action Patterns   | MEDIUM   | External API calls, Node.js runtime           |
| Scheduling        | MEDIUM   | Crons and delayed function execution          |
| File Storage      | LOW      | Blob storage and metadata                     |

## Quick Reference

### Function Registration

```typescript
// Public functions (exposed to clients)
import { query, mutation, action } from "./_generated/server";

// Internal functions (only callable from other Convex functions)
import {
  internalQuery,
  internalMutation,
  internalAction,
} from "./_generated/server";
```

### Function Syntax (Always Use This)

The rest: https://github.com/CloudAI-X/claude-workflow-v2/blob/HEAD/skills/convex-backend/SKILL.md