Skip to main content
skill CX Codex

convex-backend — skill for Claude Code: Convex backend rules

convex-backend is a Claude Code skill that loads Convex guidelines for TypeScript functions, schemas, validators, queries, mutations, actions, subscriptions, and file storage. It supports type-safe backend development.

MIT ★ 1,424 updated 2026-10-06

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow
Open on GitHub

What convex-backend does

The skill bundles reference material for Convex-specific TypeScript patterns. It covers function registration syntax, a validator table (v.string(), v.id(), v.array(), v.object(), and others), table schemas with indexes, and patterns for queries, mutations, actions, scheduled functions, and blob storage. Includes examples of public and internal function registration, the requirement to use indexes via withIndex() instead of filter(), and rules for args and returns validators on every function.

The skill triggers on Convex-related tasks: writing database functions, setting up real-time subscriptions, working with ctx.db, configuring cron jobs, or uploading files. It applies only if your project already uses Convex as its backend. The document includes a rule categories table with impact levels: CRITICAL for syntax and validators, HIGH for schemas and queries, MEDIUM for mutations and actions.

What it helps with

  • write queries with correct indexes to avoid slow full scans
  • define type-safe arguments and return values using validators
  • distinguish between public and internal functions and call them correctly
  • set up real-time subscriptions and scheduled functions
  • handle file uploads and store metadata

Example prompts for the agent

  • Write a query that fetches the last 10 messages for a channel using the by_channel index
  • Build a mutation that updates a document with type-checked arguments and returns the new value
  • Create an internal action that calls an external API and returns the response

How to install convex-backend

1Plugin marketplace

/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow

This installs the whole project-starter plugin with all its skills

2Skills CLI (Vercel)

npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a claude-code

3Manually: put the files in place

~/.claude/skills/convex-backend/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/convex-backend/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about convex-backend

How do I install convex-backend in Claude Code?

Run these commands in order: /plugin marketplace add CloudAI-X/claude-workflow-v2, then /plugin install project-starter@claude-workflow, then npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a claude-code, and open ~/.claude/skills/convex-backend/SKILL.md.

When does the convex-backend skill activate?

It activates when you write Convex functions, define table schemas, set up queries and mutations, work with real-time subscriptions, configure cron jobs, or handle file storage.

What is the difference between queries and mutations in Convex?

Queries read data only; mutations write to the database. Both require args and returns validators. Actions call external APIs and run Node.js code, but cannot write to ctx.db directly—use runMutation instead.

Source text

SKILL.md · MIT
---
name: convex-backend
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.
---

# 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)

```typescript
export const myFunction = query({
  args: { name: v.string() },
  returns: v.string(),
  handler: async (ctx, args) => {
    return "Hello " + args.name;
  },
});
```

### Common Validators

| Type     | Validator                         | Example       |
| -------- | --------------------------------- | ------------- |
| String   | `v.string()`                      | `"hello"`     |
| Number   | `v.number()`                      | `3.14`        |
| Boolean  | `v.boolean()`                     | `true`        |
| ID       | `v.id("tableName")`               | `doc._id`     |
| Array    | `v.array(v.string())`             | `["a", "b"]`  |
| Object   | `v.object({...})`                 | `{name: "x"}` |
| Optional | `v.optional(v.string())`          | `undefined`   |
| Union    | `v.union(v.string(), v.number())` | `"x"` or `1`  |
| Literal  | `v.literal("status")`             | `"status"`    |
| Null     | `v.null()`                        | `null`        |

### Function References

```typescript
// Public functions
import { api } from "./_generated/api";
api.example.myQuery; // convex/example.ts → myQuery

// Internal functions
import { internal } from "./_generated/api";
internal.example.myInternalMutation;
```

### Query with Index

```typescript
// Schema
messages: defineTable({...}).index("by_channel", ["channelId"])

// Query
await ctx.db
  .query("messages")
  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
  .order("desc")
  .take(10);
```

### Key Rules

1. **Always include `args` and `returns` validators** on all functions
2. **Use `v.null()` for void returns** - never omit return validator
3. **Use `withIndex()` not `filter()`** - define indexes in schema
4. **Use `internalQuery/Mutation/Action`** for private functions
5. **Actions cannot access `ctx.db`** - use runQuery/runMutation instead
6. **Include type annotations** when calling functions in same file

## Full Compiled Document

For the complete guide with all rules and detailed code examples, see [AGENTS.md](AGENTS.md).

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

Similar skills

All skills for Backend and APIs →

From the same set46

The whole set →
save-session-learnings The save-session-learnings command for Claude Code saves useful findings from a coding session to CLAUDE.md and AGENTS.md after debugging or a substantial task. CX Codex +1 ★ 1,424repo stars analyzing-projects analyzing-projects walks through an unfamiliar codebase step by step: stack, structure, patterns, dev commands — useful when onboarding onto a project. CX Codex +1 ★ 1,424repo stars plan Creates and maintains a structured PLAN.md file in your project root to track phases, task dependencies, and progress logs. CX Codex +1 ★ 1,424repo stars refactor-guided refactor-guided guides structural refactoring in small steps and runs tests after each change. It keeps feature work separate from code restructuring. CX Codex +1 ★ 1,424repo stars dependency-upgrade The dependency-upgrade command for Claude Code updates packages one by one, runs tests after each upgrade, and rolls back changes on failures. CX Codex +1 ★ 1,424repo stars designing-apis designing-apis — a Claude Code skill that designs REST and GraphQL APIs: structures endpoints, defines request and response formats, configures error handling and versioning. CX Codex +1 ★ 1,424repo stars parallel-analyze parallel-analyze starts four subagents at once: architecture, security, performance, testing. Their findings land in one report, ranked by priority. CX Codex +1 ★ 1,424repo stars managing-git managing-git guides Claude Code through Git workflows, branch naming conventions, Conventional Commits formatting, and pull request review checklists. CX Codex +1 ★ 1,424repo stars

Project sponsors

Companies that keep this analytics open