gmickel/my-claude-skills

Overview

This skill provides practical guidance for building reliable Convex backends, including patterns for validators, indexes, actions, queries, mutations, file storage, scheduling, and React integration. It focuses on preventing common mistakes so your code compiles and runs on first try. The guidance is concise, actionable, and oriented around real Convex conventions and pitfalls.

How this skill works

The skill inspects Convex code patterns and enforces recommended conventions: generated imports, query/action signatures, index usage, scheduler behavior, and React hook usage. It highlights forbidden patterns (like .filter() on queries or conditional hooks) and prescribes the correct replacements and code snippets. It also maps common issues to concrete fixes and a verification checklist to apply before deployment.

When to use it

• When writing new Convex queries, mutations, indexes, or actions.
• When debugging compile-time or runtime Convex errors related to DB access or scheduler behavior.
• When planning Convex app architecture or code organization.
• When integrating Convex with React components or file storage.
• When creating scheduled tasks and ensuring correct auth/context propagation.

Best practices

• Import server functions from ./_generated/server and use query({ args, handler }) signature consistently.
• Define and use indexes with .withIndex() instead of .filter(); never create a by_creation_time index.
• Add "use node" at top of all actions and avoid ctx.db; use ctx.runQuery or ctx.runMutation for DB interactions.
• For scheduled tasks, treat auth as not propagated and call internal functions explicitly.
• In React, never call hooks conditionally; use a skip pattern prop or flag to bypass logic safely.

Example use cases

• Converting a failing .filter()-based query to an indexed query using .withIndex() for performance and correctness.
• Refactoring an action that used ctx.db to instead call ctx.runMutation for safer server-side execution.
• Designing a scheduler job that invokes internal helpers and explicitly passes any required auth context.
• Implementing React hooks that accept a skip flag to avoid conditional hook calls while preserving component logic.
• Setting up file storage flows with validations and server-side checks following Convex patterns.