Convex Best Practices

Comprehensive best practices guide for building scalable Convex applications, optimized for AI agents and LLMs.

Installation

npx add-convex-best-practices-skills

To uninstall:

npx add-convex-best-practices-skills --uninstall

This installs the skill to: ~/.cursor/skills, ~/.opencode/skills, ~/.claude/skills, ~/.codex/skills, ~/.github/skills, ~/.droid/skills

Overview

This skill provides 20+ rules across 6 categories:

1. Database Performance (CRITICAL) - Indexes, queries, .collect limits
2. Security & Validation (CRITICAL) - Argument validators, access control
3. Actions & Side Effects (HIGH) - When to use actions, avoiding sequential calls
4. Async Patterns (HIGH) - Awaiting promises, workflow patterns
5. Code Organization (MEDIUM) - Helper functions, directory structure
6. React Integration (MEDIUM) - Loading states, optimistic updates

Usage

For AI Agents

The main entry point is AGENTS.md which contains all rules in a single document, optimized for context window usage.

For Humans

Browse individual rule files in the rules/ directory for detailed explanations and examples.

Rule Format

Each rule file contains:

• Title and impact level - Quick assessment of importance
• Explanation - Why the rule matters
• Incorrect example - Common anti-pattern to avoid
• Correct example - Recommended approach
• Reference - Link to official documentation

Contributing

To add a new rule:

1. Copy rules/_template.md
2. Name it with the appropriate prefix (db-, security-, action-, etc.)
3. Fill in the template with the rule details
4. Update SKILL.md quick reference
5. Regenerate AGENTS.md

Credits

• Skill structure based on vercel-labs/agent-skills
• Best practices adapted from Convex Best Practices

References

• Convex Documentation
• Convex Stack
• Convex Helpers