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
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflowWhat 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_channelindex - 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-workflowThis 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-code3Manually: put the files in place
~/.claude/skills/convex-backend/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/convex-backend/
1Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a codex2Manually: put the files in place
.agents/skills/convex-backend/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a cursor2Manually: put the files in place
.cursor/skills/convex-backend/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install CloudAI-X/claude-workflow-v2 skills/convex-backend2Manually: put the files in place
.github/skills/convex-backend/SKILL.md1Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a gemini-cli2Platform CLI
gemini skills install https://github.com/CloudAI-X/claude-workflow-v2 --path skills/convex-backendManually: put the files in place
.devin/skills/convex-backend/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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