convex-development

by @phrazzld in Tools

# Install this skill:

npx skills add phrazzld/claude-config --skill "convex-development"

Install specific skill from multi-skill repository

# Description

# SKILL.md

name: convex-development
description: |
Apply Convex database best practices for cost optimization, performance, security, and architecture.
Use when: building Convex backends, optimizing queries, handling embeddings/vector search,
reviewing Convex code, designing schemas, planning migrations, or discussing Convex architecture.
Keywords: Convex, real-time database, queries, mutations, actions, indexes, pagination,
vector search, embeddings, schema, migrations, ctx.auth, convex-helpers, bandwidth.

Convex Development

Best practices for robust, secure, performant, cost-effective Convex backends.

Core Principle

Deep modules via the convex/model/ pattern. Most logic should be plain TypeScript; query/mutation wrappers should be thin.

convex/
  _generated/         # MUST commit to git!
  model/              # Business logic (testable, reusable)
  users.ts            # Public API (thin wrappers)
  schema.ts

Critical Rules

ALWAYS commit convex/_generated/ - Required for type-checking, CI/CD, team productivity
Index what you query - .withIndex() not .filter() for efficient queries
Paginate everything - Never unbounded .collect() on user-facing queries
Trust ctx.auth only - Never user-provided auth data

Quick Reference

Need	Use
Read data reactively	`query`
Write to database	`mutation`
External APIs, vector search	`action`
Scheduled tasks	`internalMutation` / `internalAction`

Anti-Patterns Scanner

Run scripts/anti_patterns_scanner.py ./convex to detect common issues.

Detailed References

For comprehensive guidance, see:
- references/cost-mitigation.md - Bandwidth optimization, indexing, pagination
- references/embeddings-vectors.md - Vector search patterns, co-location decisions
- references/query-performance.md - Compound indexes, query segmentation, caching
- references/security-access.md - Auth patterns, RLS, RBAC, convex-helpers
- references/schema-migrations.md - Expand/Contract pattern, environment management
- references/architectural-patterns.md - File organization, state machines, naming

Philosophy

Cost First: Bandwidth is often the largest cost. Index aggressively, paginate everything.
Security First: Never trust client input. Always use ctx.auth.
Reactivity is Power: Use useQuery for real-time updates; don't forfeit with one-off fetches.
Type Safety End-to-End: Leverage Convex's full type chain from database to UI.