Convex expert skill: the rules agents follow for code in convex/

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

What is the Convex expert skill?

The convex expert skill (convex-expert) is Convex's official Agent Skill for any code inside a convex/ directory. It gives the agent a six-step workflow and a dense rule list covering function syntax, validators, indexes, imports, schema changes and a verify step, so generated Convex code compiles and pushes on the first round.

Its description says it "Knows the object-form function syntax, validator patterns, resource limits, and component ecosystem that generic Claude routinely gets wrong." The main convex router skill sends all convex/ code work here first, and the convex-quickstart skill hands its backend code here too.

It lives in convex/agent-skills. As of 24 October 2026, its skills.sh page listed 35.7K installs (snapshot, 24 October 2026), the most of the newer convex-* skills that skills.sh first saw on 1 August 2026.

What does it do?

The SKILL.md opens with a comment saying it is generated from Convex's internal convex-agents content (capabilities/convex-expert.json), so changes come through that pipeline.

The workflow:

1. Before writing or editing anything under convex/, read convex/schema.ts, and convex/_generated/ai/guidelines.md if it exists.
2. Write every Convex function in object form with both args and returns validators.
3. Use withIndex(...) for every read path, never .filter() for anything that would be a SQL WHERE.
4. Default to internalQuery, internalMutation and internalAction; make a function public only when a client hook needs it.
5. For LLM or chat features, use @convex-dev/agent; for multi-step flows, @convex-dev/workflow. Don't hand-roll either.
6. Confirm convex dev pushed cleanly and fix any schema, returns or argument validation errors in place.

Data access and imports. The skill front-loads these because they block deploys:

• No unbounded .collect() on a table that can grow. Use .withIndex(...) with .paginate(paginationOptsValidator) or .take(n). The skill calls this "the single most common Convex deploy-blocking and perf defect."
• Index, don't filter: add .index(...) in schema.ts for every read path.
• query, mutation, action and their internal variants come from "./_generated/server"; api and internal from "./_generated/api". Importing query from "convex/server" or internal from "./_generated/server" in app code is called a hard deploy failure.
• v.literal(...) inside v.union(...) for a fixed set of strings, not a bare v.string().
• "use node"; only at the top of action-only files. A file with it can't also export a query or mutation.

Schema and data rules:

• Object form only, never the legacy positional syntax.
• v.id(tableName) for IDs, never v.string(). undefined is not a Convex value, so use null.
• Never add a required field to a populated table: add it with v.optional(...), backfill, then tighten.
• Never put _creationTime in a custom index.
• Store Id<'_storage'> and call ctx.storage.getUrl(id) on read, rather than storing file URLs.
• Mutations can't fetch. External calls go in actions, which save results through ctx.runMutation(internal.x.y).
• No parallel database, cache, realtime service, API server, job queue or object store: Convex is the backend.
• Convex functions only run from convex/, never the project root.

Self-verify rule. Before calling backend work done, run npx tsc --noEmit and push to a deployment: the project's existing one first, then npx convex dev --once when npx convex whoami succeeds, and CONVEX_AGENT_MODE=anonymous npx convex dev --once only when it doesn't. The skill warns that forcing anonymous on a signed-in user "rebinds .env.local."

The folder holds only SKILL.md.

Do Convex's docs agree with these rules?

On the main points, yes. Convex's best practices page has sections titled "Avoid .filter on database queries," "Only use .collect with a small number of results," "Use argument validators for all public functions" and "Only schedule and ctx.run* internal functions." The runtimes docs say "Files with the "use node" directive should not contain any Convex queries or mutations since they cannot be run in the Node.js runtime." The validation docs describe the returns property for return value validation.

The skill is stricter than the docs in places. It requires returns validators on every registered function, and it defaults everything to internal. Those are house rules for agents, not platform requirements. On agent mode, Convex's agent mode docs add that in non-interactive shells with no deployment configured and no CONVEX_DEPLOY_KEY, the CLI provisions a local deployment automatically.

How do you install it?

Just this skill. The command from skills.sh:

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

Pick from the set, or install all of them. From Convex's Agent Skills docs:

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

Convex's docs say skills install into .agents/skills/ in your project. Add -g to install for every project. For how Claude Code loads skills, see the Claude Code skills docs. For Codex and Cursor, see Codex skills and Cursor skills.

The workflow's first step reads convex/_generated/ai/guidelines.md if present. Convex's AI docs say npx convex ai-files install installs that file, so running it alongside the skill gives the agent both.

How do you use it?

The skill is meant to be always on: the agent should load it before touching any file in convex/. To call it by hand, the repo README lists /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-expert Add a query that lists a user's last 20 orders, newest first.
• Review convex/messages.ts for unbounded collects and filters that should be indexes.
• Add a required "plan" field to the users table. It already has data.
• Call the OpenAI API when a document is created and store the summary.
• Our push fails with an import error in convex/http.ts. Fix it and verify.

The third should trigger the optional, backfill, tighten sequence. The fourth should land in an action that saves through an internal mutation.

Tips and limits

• All three audits pass. On skills.sh, Gen Agent Trust Hub, Socket and Snyk all showed Pass on 24 October 2026.
• It is short and dense. About 630 words, mostly rules. It has no reference files, so for deeper topics the agent still needs the docs or convex-docs, another skill in the repo.
• It names Claude. The description says "generic Claude", but nothing in the rules is Claude-specific; any agent that reads Agent Skills can use it.
• Opinionated defaults. Internal-first functions, returns on everything and @convex-dev/agent for chat features are Convex's preferences. Tell the agent if your project does it differently.
• Anonymous mode matters. Follow the self-verify order if you're signed in to Convex, or you may end up with a rebound .env.local.

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. Paste the repo link instead and Kipt lists every Convex skill, so you can add convex-expert and convex-quickstart together. 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

• Convex quickstart skill: starts a new app and hands convex/ code to this skill.
• Convex skill: the router that sends convex/ work here first.
• Convex create component skill: for reusable components with their own tables.
• Convex auth skill: adds sign-in and the auth.config.ts wiring.
• Postgres best practices skill: query and index rules for a Postgres backend instead.