convex-backend — скилл для Claude Code: разработка на Convex
Скилл convex-backend загружает guidelines для работы с Convex: функции, схемы, валидаторы, queries, mutations, actions, подписки и хранилище файлов. Помогает писать типобезопасный бэкенд на TypeScript.
MIT ★ 1 424 обновлён 2026-10-06
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflowЧто делает 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-code3Вручную: положить файлы
~/.claude/skills/convex-backend/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/convex-backend/
1Через Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a codex2Вручную: положить файлы
.agents/skills/convex-backend/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a cursor2Вручную: положить файлы
.cursor/skills/convex-backend/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install CloudAI-X/claude-workflow-v2 skills/convex-backend2Вручную: положить файлы
.github/skills/convex-backend/SKILL.md1Через Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill convex-backend -a gemini-cli2Командой платформы
gemini skills install https://github.com/CloudAI-X/claude-workflow-v2 --path skills/convex-backendВручную: положить файлы
.devin/skills/convex-backend/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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