A comprehensive collection of specialized skills for Claude Code that provide expert guidance on building applications with Convex. These skills draw from official Convex documentation and Convex Chef best practices to deliver production-ready patterns for real-time backend development.
This repository contains 17 specialized skills that augment Claude Code with deep expertise in:
- Core Convex: Queries, mutations, and actions
- Convex Agents: Building AI-powered conversational interfaces with the @convex-dev/agent component
- Advanced Features: File storage, HTTP endpoints, scheduling, rate limiting, and more
Each skill provides context-aware guidance, code examples, and best practices that help you build faster and avoid common pitfalls.
Simply copy the skill folders you need directly into your project's .claude/skills/ directory and restart the Claude Code cli.
Once copied, Claude Code will automatically load these skills and use them when you're working with Convex code.
| Skill | Description | Use When |
|---|---|---|
| convex-queries | Query function implementation, pagination, indexing, full-text search | Reading data, implementing search, optimizing queries |
| convex-mutations | Mutation functions, database operations (insert/patch/replace), transactions | Writing/updating data, scheduling background jobs |
| convex-actions-general | Actions, HTTP endpoints, validators, schemas, env vars, file storage, limits | External API calls, webhooks, schema design, configuration |
The @convex-dev/agent component enables building AI-powered conversational interfaces with automatic message history, tool calling, and multi-agent orchestration.
| Skill | Description | Use When |
|---|---|---|
| convex-agents-fundamentals | Agent setup, thread creation, basic text generation | Starting a new agent project, creating chat interfaces |
| convex-agents-threads | Thread management, conversation organization, metadata | Managing multi-turn conversations, per-user history |
| convex-agents-messages | Message storage, retrieval, role management | Saving/loading chat history, building message UIs |
| Skill | Description | Use When |
|---|---|---|
| convex-agents-tools | Tool calling, function execution, agent actions | Letting agents interact with your database or APIs |
| convex-agents-streaming | Real-time response streaming, UI updates | Building responsive chat interfaces with typing indicators |
| convex-agents-rag | Retrieval-augmented generation, embeddings, semantic search | Building knowledge bases, context-aware responses |
| convex-agents-workflows | Multi-step agent workflows, state machines | Complex multi-turn interactions, guided conversations |
| Skill | Description | Use When |
|---|---|---|
| convex-agents-human-agents | Human-in-the-loop patterns, escalation | Building approval workflows, human oversight |
| convex-agents-context | Context management, conversation memory | Managing long conversations, context windows |
| Skill | Description | Use When |
|---|---|---|
| convex-agents-rate-limiting | Rate limiting, quota management, usage controls | Preventing abuse, managing API costs |
| convex-agents-usage-tracking | Token counting, cost tracking, analytics | Monitoring usage, billing, optimization |
| convex-agents-files | File handling in conversations, attachments | Processing uploaded documents, images |
| convex-agents-debugging | Debugging agents, logging, error handling | Troubleshooting agent behavior, monitoring |
| convex-agents-playground | Testing agents, experimentation environment | Development, testing different prompts/models |
Each skill follows a consistent structure:
skill-name/
├── SKILL.md # Main skill documentation with examples
├── references/ # Detailed reference documentation
│ └── *.md
├── scripts/ # Helper scripts (if applicable)
└── assets/ # Images, diagrams (if applicable)
These principles are reinforced throughout the skill collection:
- Always use validators - Every function must have argument validators
- Avoid
filter()in queries - Use indexes withwithIndex()instead - Auth doesn't propagate - Scheduled jobs have null auth; use internal functions
- Type safety - Use
Id<"table">andDoc<"table">types - ASCII field names - Object keys must be ASCII (no emoji)
- Return type annotations - Add explicit returns to avoid circular references
- Transaction awareness - Understand mutation transaction boundaries
- Respect limits - 1 second for queries/mutations, 8192 writes, 16384 reads
To add new skills or improve existing ones:
- Follow the existing skill structure (SKILL.md + references/)
- Include practical code examples
- Reference official Convex documentation
- Test examples in real projects
- Keep focused on specific use cases
This collection is designed for use with Claude Code and Convex. Refer to individual component licenses:
- Claude Code: Anthropic License
- Convex: Convex License
This collection is maintained to stay current with:
- Convex platform updates
- @convex-dev/agent component changes
- Claude Code best practices
- Community feedback and patterns
Ready to build with Convex? Copy these skills to your .claude/skills/ directory and let Claude Code guide you through building real-time, AI-powered applications.