Convex skill: convex-quickstart for Claude Code and Codex

Source: convex/agent-skills · Maintainer: Convex · License: Apache-2.0 · Checked: 24 October 2026

What is the Convex skill?

The Convex skill with the most installs is convex-quickstart, Convex's official Agent Skill for getting a barebones Next.js and Convex app running locally from a one-sentence idea. It also carries a compact list of Convex rules that stop agents from writing code that type-checks but fails at push time.

Its SKILL.md description reads: "Get a barebones Convex + web template running from a one-sentence idea." The heading underneath says it will "Stand up a barebones Next.js + Convex template from the idea, locally, with an anonymous dev deployment. Minimal by design: local dev servers, no publish step, no pre-baked auth."

It lives in convex/agent-skills, which the README describes as "Agent skills for common Convex workflows." As of 24 October 2026, its skills.sh page listed 130.5K installs (snapshot, 24 October 2026).

What does it do?

The SKILL.md has a three-step workflow and a long rules section. A comment at the top says the file is generated from Convex's internal convex-agents content, so edits land through that pipeline rather than by hand.

The workflow:

1. Run a recipe called quickstart-recipe@^2 with your idea and a template. The skill says it "creates the project, installs deps, starts the backend (anonymous) and the web dev server."
2. Open the dev URL for you when it prints.
3. Present a short plan and confirm with you before building anything beyond the template.

The rules, in short:

• Don't re-run the recipe once it has reported success.
• Hand code under convex/ to the convex-expert capability, which is a separate skill in the same repo.
• Don't add Postgres, Redis or Express; use Convex primitives.
• Don't add hosting, publishing or auth unless you ask.
• Degradation rule. If the scaffold can't run (non-interactive session, no network, a sandboxed temp directory, or you just want code), write a standard Convex project directly. "ALL backend code goes under convex/ (schema.ts, functions)." No START_HERE.md or architecture files unless asked: "'Build me a backend' means code, not ceremony."
• Data access. Never an unbounded .collect() on a growing table; use .withIndex(...) with .paginate(...) or .take(n), and an index rather than .filter() for anything that would be a SQL WHERE. Convex's indexes docs cover the same idea.
• Imports. query, mutation, action and their internal variants come from ./_generated/server; api and internal from ./_generated/api; never convex/server in app code.
• Node runtime. "use node" only at the top of action-only files, and no Node built-ins such as crypto or fs in files without it. Prefer Web Crypto.
• Reserved names. No JavaScript reserved words as export names, and no table or index names starting with _.
• HTTP routes. httpRouter has no Express-style :param segments; use pathPrefix and parse the rest yourself. Every handler must be wrapped in httpAction(...). See Convex's HTTP actions docs.
• Function references. ctx.runQuery, ctx.runMutation and ctx.runAction need api.foo.bar or internal.foo.bar, not an imported module member.
• Self-verify. Before calling backend work done, run npx tsc --noEmit and push to a deployment.

The folder holds only SKILL.md, agents/openai.yaml (Codex display name "Convex Quickstart" and a default prompt) and an icon.

How do you install the Convex skill?

Just this skill. The command from skills.sh:

npx skills add https://github.com/convex/agent-skills --skill convex-quickstart

Pick from the whole set, or take everything. From the repo README:

npx skills add get-convex/agent-skills
npx skills add get-convex/agent-skills --all

get-convex/agent-skills now redirects to convex/agent-skills on GitHub. Because the quickstart hands Convex code to convex-expert, installing that skill too makes sense:

npx skills add https://github.com/convex/agent-skills --skill convex-quickstart --skill convex-expert

Add -g to install for all projects. Claude Code reads skills from .claude/skills/ or ~/.claude/skills/ (see the Claude Code skills docs). For Codex and Cursor, see Codex skills and Cursor skills.

Convex's own AI docs describe a separate route: the Convex CLI can install and maintain AI helper files, a list that includes agent skills installed via npx skills, with npx convex ai-files install.

How do you use it?

The README says skills apply automatically when relevant, and lists manual invocation as /skill-name in Claude Code, Cursor and VS Code, $skill-name in Codex and @skill-name in Windsurf.

Example prompts (suggestions, not quotes from the repo):

• /convex-quickstart A shared grocery list that updates live for everyone in the household.
• Start a new Convex app for tracking reading habits. Keep it minimal, no auth yet.
• Just give me the Convex backend code for a comments system: schema and functions, no scaffold.
• Set up a Convex project here and verify it pushes before you build any features.

The third prompt should trigger the degradation rule: code under convex/, no template, no docs files.

Tips and limits

• All three audits pass. On skills.sh, Gen Agent Trust Hub, Socket and Snyk all showed Pass on 24 October 2026.
• The recipe isn't in this repo. The SKILL.md says "the pack fetches + caches it" with a "pinned offline fallback", but the folder contains no recipe and the repo doesn't document how it runs. If your agent can't run it, expect the degradation rule to kick in.
• Anonymous mode and your login. The self-verify rule says to push to your existing deployment first, use npx convex dev --once when npx convex whoami succeeds, and set CONVEX_AGENT_MODE=anonymous only when it does not, because forcing anonymous on a signed-in user "rebinds .env.local". Convex's agent mode docs add that in non-interactive shells with no deployment configured and no deploy key, the CLI provisions a local deployment automatically.
• The README lags the folder. It lists six skills, some of which (such as convex-setup-auth) no longer exist as folders, while skills/ now holds over 30, including convex-auth, convex-migrate and convex-optimize.
• Next.js by default. The template is Next.js; say so if you want something else, and expect the agent to confirm before going further.

Under Apache 2.0 you can copy and modify the skill as long as you keep the license and notices and mark files you change.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and agents/openai.yaml. Paste the repo link instead and Kipt shows the list of Convex skills, so you can add convex-expert in the same step. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Convex.

Similar skills

• Firebase basics skill: Firebase's official skill for CLI login, project setup and config files.
• Supabase skill: the official Supabase skill for Postgres, auth, storage and realtime.
• Neon Postgres skill: serverless Postgres with branching.
• Prisma skill: Prisma's official skills, if you'd rather keep a SQL database behind an ORM.