convex-runtime

Q: How do I install convex-runtime?

Run npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-runtime in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/convex-runtime/ (personal) or .claude/skills/convex-runtime/ (project).

by igorwarzochaAI & Agents

Implement Convex runtime features: HTTP actions, file storage, search (full text + vector), scheduling (crons + scheduled functions), and RAG patterns. Use for webhooks, uploads, search indexes, vectorSearch actions, and background workflows. Use proactively when users mention HTTP endpoints, files, search, embeddings, or cron/schedule. Examples: - user: "Add full text search" → define searchIndex + withSearchIndex query - user: "Upload files" → generate upload URL and persist storageId - user: "Vector search" → action with ctx.vectorSearch and doc fetch - user: "Run cleanup nightly" → cronJobs + function reference

Installs: 92
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-runtime

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads convex-runtime automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

<overview> Implement Convex runtime features: HTTP actions, file storage, search (full text + vector), and scheduling. </overview> <reference> - **HTTP actions**: https://docs.convex.dev/functions/http-actions - **File storage**: https://docs.convex.dev/file-storage - **Uploading files**: https://docs.convex.dev/file-storage/upload-files - **Serving files**: https://docs.convex.dev/file-storage/serve-files - **File metadata**: https://docs.convex.dev/file-storage/file-metadata - **Full text search**: https://docs.convex.dev/search/text-search - **Vector search**: https://docs.convex.dev/search/vector-search - **Scheduling**: https://docs.convex.dev/scheduling - **Scheduled functions**: https://docs.convex.dev/scheduling/scheduled-functions - **Cron jobs**: https://docs.convex.dev/scheduling/cron-jobs </reference> <context name="Runtime Concepts"> - Full text search: `searchIndex` with `searchField` and optional `filterFields`; relevance-ordered; prefix matching on final term; fuzzy matches are deprecated; limits 16 terms, 8 filters, 1024 scanned. - Vector search: `vectorIndex` with `vectorField` and `dimensions` (2-4096); vector field is `v.array(v.float64())`; actions-only; limits 256 results, 64 filters, 4 vector indexes per table. - Scheduling: scheduled functions are durable and stored in DB; cron jobs run on fixed schedules; auth not propagated, You MUST pass identity explicitly. - File storage: upload URLs for large files; HTTP action uploads limited to 20MB; metadata in `_storage`. </context> <rules>

Runtime Operations

HTTP actions: define handlers with httpAction, register in convex/http.ts via httpRouter (default export REQUIRED).

HTTP Syntax:

http.route({
  path: "/api/echo", // Exact path
  method: "POST",
  handler: httpAction(async (ctx, req) => {
    const body = await req.bytes();
    return new Response(body, { status: 200 });
  }),
});

HTTP actions MUST be exposed at https://<deployment>.convex.site.
Upload URL flow: generate URL mutation → client POST → store storageId; URLs expire after 1 hour.
HTTP upload flow: ctx.storage.store(blob) then mutation. Uploads via HTTP actions are limited to 20MB.
Serving files: ctx.storage.getUrl(storageId) in queries/mutations; returns signed URL or null.
File metadata: ctx.db.system.get("_storage", id) or query("_storage"); storage.getMetadata() is deprecated.
Scheduling: ctx.scheduler.runAfter/runAt; cron jobs in convex/crons.ts using cronJobs().
Cron Scheduling: You MUST use crons.interval or crons.cron. You MUST NOT use deprecated helpers like crons.hourly, crons.daily, or crons.weekly.
Cron internal calls: If a cron calls an internal function, You MUST import the internal object from _generated/api to reference it, even if defined in the same file.

Core Rules

HTTP actions MUST be routed only via convex/http.ts default export.
HTTP actions MUST parse Request manually as they do not support validators.

Search Example:

const messages = await ctx.db.query("messages")
  .withSearchIndex("search_body", (q) =>
    q.search("body", "hello hi").eq("channel", "#general")
  ).take(10);

Vector search MUST be actions-only; results are non-reactive.
Search behavior: full text search is relevance-ordered and uses prefix matching on the final term; fuzzy matches are deprecated.
You SHOULD prefer search/vector filters in index definitions and query filters.
Scheduled functions MUST remain backward compatible with args.

</rules>

FAQ

What does the convex-runtime skill do?

How do I install convex-runtime?

Run npx skills add https://github.com/igorwarzocha/opencode-workflows --skill convex-runtime in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/convex-runtime/ (personal) or .claude/skills/convex-runtime/ (project).

Which AI agents can use convex-runtime?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is convex-runtime safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains convex-runtime?

It is published by igorwarzocha in igorwarzocha/opencode-workflows. It has 92 recorded installs.