Convex workflow skill. Use this skill when the user needs Convex reactive backend expert: schema design, TypeScript functions, real-time subscriptions, auth, file storage, scheduling, and deployment and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
Convex workflow skill. Use this skill when the user needs Convex reactive backend expert: schema design, TypeScript functions, real-time subscriptions, auth, file storage, scheduling, and deployment and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
This public intake copy packages plugins/antigravity-awesome-skills/skills/convex from https://github.com/sickn33/antigravity-awesome-skills into the native Omni Skills editorial shape without hiding its origin.
Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.
This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.
Convex You are an expert in Convex — the open-source, reactive backend platform where queries are TypeScript code. You have deep knowledge of schema design, function authoring (queries, mutations, actions), real-time data subscriptions, authentication, file storage, scheduling, and deployment workflows across React, Next.js, Angular, Vue, Svelte, React Native, and server-side environments.
Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Core Concepts, Schema Design, Writing Functions, Client-Side Integration, Scheduling & Cron Jobs, File Storage.
When to Use This Skill
Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.
Use when building a new project with Convex as the backend
Use when adding Convex to an existing React, Next.js, Angular, Vue, Svelte, or React Native app
Use when designing schemas for a Convex document-relational database
Use when writing or debugging Convex functions (queries, mutations, actions)
Use when implementing real-time/reactive data patterns
Use when setting up authentication with Convex Auth or third-party providers (Clerk, Auth0, etc.)
Operating Table
Situation
Start here
Why it matters
First-time use
metadata.json
Confirms repository, branch, commit, and imported path through the external_source block before touching the copied workflow
Provenance review
ORIGIN.md
Gives reviewers a plain-language audit trail for the imported source
Workflow execution
SKILL.md
Starts with the smallest copied file that materially changes execution
Supporting context
SKILL.md
Adds the next most relevant copied source file without loading the entire package
Handoff decision
## Related Skills
Helps the operator switch to a stronger native skill when the task drifts
Workflow
This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.
Prompts you to log in (GitHub)
Creates a project and deployment
Generates convex/ folder for backend functions
Syncs functions to your dev deployment in real-time
Creates .env.local with CONVEXDEPLOYMENT and NEXTPUBLICCONVEXURL
Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
Read the overview and provenance files before loading any copied upstream support files.
Imported Workflow Notes
Imported: Project Setup
New Project (Next.js)
npx create-next-app@latest my-app
cd my-app && npm install convex
npx convex dev
Add to Existing Project
npm install convex
npx convex dev
The npx convex dev command:
Prompts you to log in (GitHub)
Creates a project and deployment
Generates convex/ folder for backend functions
Syncs functions to your dev deployment in real-time
Creates .env.local with CONVEX_DEPLOYMENT and NEXT_PUBLIC_CONVEX_URL
Convex is a document-relational database with a fully managed backend. Key differentiators:
Reactive by default: Queries automatically re-run and push updates to all connected clients when underlying data changes
TypeScript-first: All backend logic — queries, mutations, actions, schemas — is written in TypeScript
ACID transactions: Serializable isolation with optimistic concurrency control
No infrastructure to manage: Serverless, scales automatically, zero config
End-to-end type safety: Types flow from schema → backend functions → client hooks
Function Types
Type
Purpose
Can Read DB
Can Write DB
Can Call External APIs
Cached/Reactive
Query
Read data
✅
❌
❌
✅
Mutation
Write data
✅
✅
❌
❌
Action
Side effects
via runQuery
via runMutation
✅
❌
HTTP Action
Webhooks/custom endpoints
via runQuery
via runMutation
✅
❌
Examples
Example 1: Ask for the upstream workflow directly
Use @convex-v2 to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.
Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.
Example 2: Ask for a provenance-grounded review
Review @convex-v2 against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.
Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.
Example 3: Narrow the copied support files before execution
Use @convex-v2 for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.
Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.
Example 4: Build a reviewer packet
Review @convex-v2 using the copied upstream files plus provenance, then summarize any gaps before merge.
Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.
Best Practices
Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.
✅ Define schemas — adds type safety across your entire stack
✅ Use indexes for queries — avoids full table scans
✅ Use compound indexes with equality filters first, range filter last
✅ Rely on native determinism — Date.now() and Math.random() are 100% safe to use in queries and mutations because Convex freezes time at the start of every function execution!
✅ Use v.id("tableName") for document references instead of plain strings
✅ Use actions for external API calls (never call external APIs from queries or mutations)
✅ Use ctx.runQuery / ctx.runMutation from actions — never access ctx.db directly in actions
Imported Operating Notes
Imported: Best Practices
✅ Define schemas — adds type safety across your entire stack
✅ Use indexes for queries — avoids full table scans
✅ Use compound indexes with equality filters first, range filter last
✅ Rely on native determinism — Date.now() and Math.random() are 100% safe to use in queries and mutations because Convex freezes time at the start of every function execution!
✅ Use v.id("tableName") for document references instead of plain strings
✅ Use actions for external API calls (never call external APIs from queries or mutations)
✅ Use ctx.runQuery / ctx.runMutation from actions — never access ctx.db directly in actions
✅ Add argument validators to all functions — they enforce runtime type safety
✅ Return null when a document isn't found instead of throwing an error unless missing is exceptional
✅ Prefer withIndex over .filter() for query performance
Troubleshooting
Problem: The operator skipped the imported context and answered too generically
Symptoms: The result ignores the upstream workflow in plugins/antigravity-awesome-skills/skills/convex, fails to mention provenance, or does not use any copied source files at all.
Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.
Problem: The imported workflow feels incomplete during review
Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task.
Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.
Problem: The task drifted into a different specialization
Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better.
Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.
Related Skills
@00-andruia-consultant - Use when the work is better handled by that native specialization after this imported skill establishes context.
@00-andruia-consultant-v2 - Use when the work is better handled by that native specialization after this imported skill establishes context.
@10-andruia-skill-smith - Use when the work is better handled by that native specialization after this imported skill establishes context.
@10-andruia-skill-smith-v2 - Use when the work is better handled by that native specialization after this imported skill establishes context.
Additional Resources
Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.
Resource family
What it gives the reviewer
Example path
references
copied reference notes, guides, or background material from upstream
references/n/a
examples
worked examples or reusable prompts copied from upstream
examples/n/a
scripts
upstream helper scripts that change execution or validation
scripts/n/a
agents
routing or delegation notes that are genuinely part of the imported package
agents/n/a
assets
supporting assets or schemas copied from the source package
Convex also has a community component (@convex-dev/better-auth) that integrates the Better Auth library directly into the Convex backend. This is currently in early alpha.
Better Auth provides email/password, social logins, two-factor authentication, and session management — all running inside Convex functions rather than an external auth server.
Angular Integration
Convex does not have an official Angular client library, but Angular apps can use the core convex package directly with Angular's Dependency Injection and Signals.
Note: The community library @robmanganelly/ngx-convex provides a more Angular-native experience with React-like hooks adapted for Angular DI and Signals.
# Set environment variables for your deployment
npx convex envset OPENAI_API_KEY sk-...
npx convex envset SENDGRID_API_KEY SG...
# List current env vars
npx convex env list
# Remove an env var
npx convex envunset OPENAI_API_KEY
Access in actions (NOT in queries or mutations):
// Only available in actionsconst apiKey = process.env.OPENAI_API_KEY;
Imported: Deployment & CLI
# Development (watches for changes, syncs to dev deployment)
npx convex dev
# Deploy to production
npx convex deploy
# Import data
npx convex import --table tasks data.jsonl
# Export data
npx convex export --path ./backup
# Open Convex dashboard
npx convex dashboard
# Run a function from CLI
npx convex run tasks:list
# View logs
npx convex logs
Imported: Anti-Patterns to Avoid
❌ External API calls in queries/mutations: Only actions can call external services. Queries and mutations run in the Convex transaction engine.
❌ Doing slow CPU-bound work in mutations: Mutations block database commits; offload heavy processing to actions.
❌ Using .collect() on large tables without limits: Fetches all documents into memory. Use .take(N) or .paginate().
❌ Skipping schema definition: Without a schema you lose end-to-end type safety, the main Convex advantage.
❌ Using .filter() instead of indexes: .filter() does a full table scan. Define an index and use .withIndex().
❌ Storing large blobs in documents: Use Convex file storage (_storage) for files; keep documents lean.
❌ Circular runQuery/runMutation chains: Actions calling mutations that schedule actions can create infinite loops.
Imported: Common Pitfalls
Problem: "Query returns undefined on first render"
Solution: This is expected — Convex queries are async. Check for undefined before rendering (this means loading, not empty).
Problem: "Mutation throws Document not found"
Solution: Documents may have been deleted between your read and write due to optimistic concurrency. Re-read inside the mutation.
Problem: "process.env is undefined in query/mutation"
Solution: Environment variables are only accessible in actions (not queries or mutations) because queries/mutations run in the deterministic transaction engine.
Problem: "Function handler is too slow"
Solution: Add indexes for your query patterns. Use withIndex() instead of .filter(). For complex operations, break into smaller mutations.
Problem: "Schema push fails with existing data"
Solution: Convex validates existing data against new schemas. Either migrate existing documents first, or use v.optional() for new fields.
