How do I install the Convex skill?

Run npx skillmds@latest add aaronvanston/convex in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Convex safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Convex?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Convex free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Convex?

aaronvanston (@aaronvanston) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Convex by aaronvanston — Agent Skill

Name: Convex
Author: aaronvanston

Convex

Convex backend development - queries, mutations, actions, schemas, indexes, realtime subscriptions, optimistic updates, file storage, HTTP endpoints, webhooks, cron jobs, migrations, AI/LLM agents, RAG, security, authentication, authorization, rate limiting, error handling with ConvexError, code review, convex-helpers, custom functions, triggers, row-level security, relationship helpers, Hono, CORS, Zod validation, CRUD, manual pagination, QueryStreams, query caching, sessions, workpool, components, RBAC, audit trails. Use when writing Convex functions, defining schemas, building real-time features, integrating external APIs, handling file uploads, setting up scheduled jobs, performing database migrations, building AI chat interfaces, reviewing Convex code for production readiness, using convex-helpers patterns, or building reusable Convex components.

aaronvanston 3657094 32 files · 134.7 KB Updated Sep 17, 2026

File contents

Convex Development

Workflow

Starting a project - See patterns for structure, types, validators
Database queries - See queries for indexes, filtering, performance
Actions and scheduling - See actions for external APIs, transactions
Realtime features - See realtime for subscriptions, optimistic updates
HTTP endpoints - See http for webhooks, REST, CORS
File handling - See file-storage for uploads, serving
Background jobs - See cron for scheduled functions
Schema changes - See migrations for data evolution
AI integration - See agents for LLM chat, RAG, tool calling
Security - See security for auth, ConvexError, ESLint, access control
Code review - See review for production readiness checklist
Components - See components for reusable Convex packages

convex-helpers (npm package)

Custom functions & Zod - See helpers-functions for middleware, auth wrappers, Zod validation
Data helpers - See helpers-data for relationships, CRUD, triggers, filter, pagination
Security helpers - See helpers-security for RLS, rate limiting, sessions, CORS
Async helpers - See helpers-async for workpool, action retries, migrations
Validation helpers - See helpers-validation for validator utils, Standard Schema, codegen
Integration helpers - See helpers-integrations for Hono, query caching, useQuery, QueryStreams

Key Principles

Always define args AND returns validators on every function
Use ConvexError with structured codes, not plain Error
Use .withIndex() not .filter() for database queries
Use internal.* (never api.*) for scheduling and ctx.run* calls
Use "use node"; only when you need Node.js APIs
Keep business logic in convex/model/ helpers, thin public API wrappers
Always await promises (ctx.db.*, ctx.scheduler.*)
Install @convex-dev/eslint-plugin for build-time validation

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Security	CRITICAL	`security-`
2	Validation	HIGH	`validation-`
3	Performance	HIGH	`performance-`
4	Code Quality	MEDIUM	`code-quality-`

1. Security (CRITICAL)

security-auth-check - Always check authentication in public functions
security-internal-functions - Use internal functions for scheduling and ctx.run calls
security-row-level-access - Verify row-level ownership before mutations
security-convex-error - Use ConvexError instead of plain Error
security-rate-limiting - Implement rate limiting for public mutations
security-table-name - Include table name in ctx.db calls

2. Validation (HIGH)

validation-return-types - Always define return validators on functions

3. Performance (HIGH)

performance-no-filter - Use .withIndex() instead of .filter() on queries
performance-bounded-collect - Only use .collect() with bounded result sets
performance-no-date-now - Don't use Date.now() in query functions

4. Code Quality (MEDIUM)

code-quality-await-promises - Always await async operations

How to Use

Read individual rule files for detailed explanations and code examples:

rules/security-auth-check.md
rules/performance-no-filter.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation

---name: convexdescription: Convex backend development - queries, mutations, actions, schemas, indexes, realtime subscriptions, optimistic updates, file storage, HTTP endpoints, webhooks, cron jobs, migrations, AI/LLM agents, RAG, security, authentication, authorization, rate limiting, error handling with ConvexError, code review, convex-helpers, custom functions, triggers, row-level security, relationship helpers, Hono, CORS, Zod validation, CRUD, manual pagination, QueryStreams, query caching, sessions, workpool, components, RBAC, audit trails. Use when writing Convex functions, defining schemas, building real-time features, integrating external APIs, handling file uploads, setting up scheduled jobs, performing database migrations, building AI chat interfaces, reviewing Convex code for production readiness, using convex-helpers patterns, or building reusable Convex components.---# Convex Development## Workflow1. **Starting a project** - See [patterns](references/patterns.md) for structure, types, validators2. **Database queries** - See [queries](references/queries.md) for indexes, filtering, performance3. **Actions and scheduling** - See [actions](references/actions.md) for external APIs, transactions4. **Realtime features** - See [realtime](references/realtime.md) for subscriptions, optimistic updates5. **HTTP endpoints** - See [http](references/http.md) for webhooks, REST, CORS6. **File handling** - See [file-storage](references/file-storage.md) for uploads, serving7. **Background jobs** - See [cron](references/cron.md) for scheduled functions8. **Schema changes** - See [migrations](references/migrations.md) for data evolution9. **AI integration** - See [agents](references/agents.md) for LLM chat, RAG, tool calling10. **Security** - See [security](references/security.md) for auth, ConvexError, ESLint, access control11. **Code review** - See [review](references/review.md) for production readiness checklist12. **Components** - See [components](references/components.md) for reusable Convex packages### convex-helpers (npm package)13. **Custom functions & Zod** - See [helpers-functions](references/helpers-functions.md) for middleware, auth wrappers, Zod validation14. **Data helpers** - See [helpers-data](references/helpers-data.md) for relationships, CRUD, triggers, filter, pagination15. **Security helpers** - See [helpers-security](references/helpers-security.md) for RLS, rate limiting, sessions, CORS16. **Async helpers** - See [helpers-async](references/helpers-async.md) for workpool, action retries, migrations17. **Validation helpers** - See [helpers-validation](references/helpers-validation.md) for validator utils, Standard Schema, codegen18. **Integration helpers** - See [helpers-integrations](references/helpers-integrations.md) for Hono, query caching, useQuery, QueryStreams## Key Principles- Always define `args` AND `returns` validators on every function- Use `ConvexError` with structured codes, not plain `Error`- Use `.withIndex()` not `.filter()` for database queries- Use `internal.*` (never `api.*`) for scheduling and `ctx.run*` calls- Use `"use node";` only when you need Node.js APIs- Keep business logic in `convex/model/` helpers, thin public API wrappers- Always `await` promises (`ctx.db.*`, `ctx.scheduler.*`)- Install `@convex-dev/eslint-plugin` for build-time validation## Rule Categories by Priority| Priority | Category | Impact | Prefix ||----------|----------|--------|--------|| 1 | Security | CRITICAL | `security-` || 2 | Validation | HIGH | `validation-` || 3 | Performance | HIGH | `performance-` || 4 | Code Quality | MEDIUM | `code-quality-` |### 1. Security (CRITICAL)- `security-auth-check` - Always check authentication in public functions- `security-internal-functions` - Use internal functions for scheduling and ctx.run calls- `security-row-level-access` - Verify row-level ownership before mutations- `security-convex-error` - Use ConvexError instead of plain Error- `security-rate-limiting` - Implement rate limiting for public mutations- `security-table-name` - Include table name in ctx.db calls### 2. Validation (HIGH)- `validation-return-types` - Always define return validators on functions### 3. Performance (HIGH)- `performance-no-filter` - Use .withIndex() instead of .filter() on queries- `performance-bounded-collect` - Only use .collect() with bounded result sets- `performance-no-date-now` - Don't use Date.now() in query functions### 4. Code Quality (MEDIUM)- `code-quality-await-promises` - Always await async operations## How to UseRead individual rule files for detailed explanations and code examples:```rules/security-auth-check.mdrules/performance-no-filter.md```Each rule file contains:- Brief explanation of why it matters- Incorrect code example with explanation- Correct code example with explanation

Frequently asked questions