К основному содержанию
скилл CX Codex

convex-backend — скилл для Claude Code: разработка на Convex

Скилл convex-backend загружает guidelines для работы с Convex: функции, схемы, валидаторы, queries, mutations, actions, подписки и хранилище файлов. Помогает писать типобезопасный бэкенд на TypeScript.

MIT ★ 1 424 обновлён 2026-10-06

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow
Открыть на GitHub

Что делает convex-backend

Скилл содержит правила синтаксиса Convex-функций, таблицу валидаторов (v.string(), v.id(), v.array(), v.object() и прочие), схемы для определения таблиц и индексов, а также паттерны для queries, mutations, actions, крон-джобов и работы с хранилищем файлов. Внутри — примеры регистрации функций через query, mutation, action и их internal версий, правила использования индексов вместо filter(), требования к args и returns на каждой функции.

Тригиры скилла срабатывают на задачах с Convex: когда нужно писать функции для базы данных, real-time подписки, работать с ctx.db, настраивать cron-джобы или загружать файлы. Скилл подходит, если проект уже использует Convex как бэкенд; если нет — срабатывать не будет.

В документе есть таблица категорий правил с весами (CRITICAL для синтаксиса и валидаторов, HIGH для схем и queries, MEDIUM для mutations и actions). Действует для Claude Code, доступен также для Codex, Cursor, GitHub Copilot, Gemini CLI и Windsurf.

Какие задачи решает

  • писать queries с правильными индексами и избежать медленного filter()
  • определять типобезопасные аргументы и возвращаемые значения функций через валидаторы
  • отличать public функции от internal и вызывать их из контекста
  • настраивать real-time подписки и крон-джобы
  • работать с file storage и хранить метаданные

Примеры запросов агенту

  • Напиши query для получения последних 10 сообщений по channelId с использованием индекса by_channel
  • Создай mutation для обновления документа с типобезопасными аргументами
  • Напиши internal action, который вызывает внешний API и возвращает результат

Как установить convex-backend

1Через маркетплейс плагинов

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

Команда ставит плагин project-starter целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

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

3Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/convex-backend/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о convex-backend

Как установить convex-backend в Claude Code?

Выполни последовательно: /plugin marketplace add CloudAI-X/claude-workflow-v2, затем /plugin install project-starter@claude-workflow, потом npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a claude-code и открой ~/.claude/skills/convex-backend/SKILL.md.

Когда срабатывает скилл convex-backend?

Когда ты пишешь Convex-функции, определяешь схемы таблиц, настраиваешь queries и mutations, работаешь с real-time подписками, крон-джобами или file storage.

В чём главное отличие queries и mutations в Convex?

Queries только читают данные; mutations пишут в базу. Обе требуют валидаторов args и returns. Actions вызывают внешние API и имеют доступ к Node.js, но не могут писать напрямую в ctx.db — используют runMutation.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
convex-create-component convex Скилл convex-create-component для Claude Code и Codex создаёт переиспользуемые Convex-компоненты с изолированными таблицами и чётким API. Выделяет backend-логику в отдельный модуль, владеющий своими данными. CX Codex +1 138 900установок convex convex Скилл-маршрутизатор для работы с бэкендом Convex: отправляет задачу нужному навыку из набора convex-* и подтягивает свежие инструкции из серверного каталога. CX Codex +1 116 100установок convex-best-practices waynesutton Скилл convex-best-practices учит агента писать надёжный бэкенд на Convex без конфликтов записи OCC. Помогает настроить валидаторы, индексы и правила @convex-dev/eslint-plugin. CX Codex +1 3 900установок convex-functions waynesutton Скилл convex-functions пишет query, mutation и action для Convex в объектной форме: с валидаторами args и returns, правильным ctx и обработкой ошибок. CX Codex +1 3 200установок convex-cursorrules-prompt-file PatrickJS Правило convex-cursorrules-prompt-file для Cursor задаёт соглашения по Convex: синтаксис функций, HTTP-маршруты и валидаторы. CX Codex +1 ★ 41 178звёзд репо create-a-backend vercel Скилл create-a-backend подбирает архитектуру бэкенда на платформе Vercel под конкретные задачи проекта. Он помогает определиться с компонентами до написания кода реализации. CX Codex +1 708установок

Из того же набора46

Весь набор →
save-session-learnings Команда save-session-learnings переносит важные выводы из сессии в CLAUDE.md и AGENTS.md. Запускайте её после отладки или крупной задачи, чтобы сохранить контекст для следующих сессий. CX Codex +1 ★ 1 424звёзд репо analyzing-projects Скилл analyzing-projects разбирает незнакомый репозиторий по шагам: стек, структура, паттерны, команды разработки — пригодится при входе в новый проект. CX Codex +1 ★ 1 424звёзд репо plan Создаёт и ведёт файл PLAN.md в корне проекта для фиксации этапов разработки, зависимостей между задачами и лога прогресса. CX Codex +1 ★ 1 424звёзд репо refactor-guided Команда refactor-guided проводит структурный рефакторинг по шагам и проверяет тесты после каждого изменения. Подходит для безопасной перестройки кода без добавления функций. CX Codex +1 ★ 1 424звёзд репо dependency-upgrade Команда dependency-upgrade для Claude Code поочерёдно обновляет зависимости, запускает тесты после каждого пакета и откатывает изменения при ошибках. CX Codex +1 ★ 1 424звёзд репо designing-apis Скилл designing-apis в Claude Code проектирует REST и GraphQL API: структурирует эндпоинты, описывает форматы запросов и ответов, настраивает обработку ошибок и версионирование. CX Codex +1 ★ 1 424звёзд репо parallel-analyze Команда parallel-analyze запускает четыре субагента разом: архитектура, безопасность, производительность и тесты. Сводит их находки в один отчёт с приоритетами. CX Codex +1 ★ 1 424звёзд репо managing-git Скилл managing-git помогает Claude Code вести ветки по GitHub Flow или Git Flow, оформлять коммиты по Conventional Commits и готовить пулл-реквесты по чек-листам. CX Codex +1 ★ 1 424звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой