How to use the Convex Code Reviewer agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. When the skill is installed, the agent can load these instructions and follow them when a request matches the skill's description.

The convex-reviewer skill makes the agent review code in a Convex project's convex/ directory using a fixed checklist, in three passes. The first pass covers security: whether public functions check ctx.auth.getUserIdentity(), whether resource ownership is verified before reads and writes, whether client-provided user IDs are trusted, and whether scheduled functions target internal.* rather than api.*. The second pass covers performance: no .filter() on database queries (use withIndex), indexes on foreign-key fields, no Date.now() in query handlers, and no .collect() on unbounded queries. The third pass covers code quality: args and returns validators on public functions, no any types, awaited promises, and bounded arrays in documents (under 8192 elements).

• Critical: missing auth checks on public mutations, which the skill describes as a data-loss risk.
• Important: .filter() on database queries, Date.now() in query handlers, missing args or returns validators, and scheduling to api.* instead of internal.*.
• Suggestion: lower-severity findings.
• Each finding comes with an explanation of why it matters and a suggested fix.

Install the convex-reviewer skill

Download the ZIP for this skill from this page. The package contains a single file, SKILL.md. Unzip it so the convex-reviewer folder containing SKILL.md ends up in one of the following locations.

For a personal install available to all your projects, place it in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder so it applies only to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/convex-reviewer/
• Project only: .claude/skills/convex-reviewer/ inside your project

Trigger the skill with a natural request

You do not need a special command. The skill's description says it is for reviewing or auditing Convex functions before shipping, so ask the agent in those terms. Point it at the convex/ folder so it knows where the code lives.

Good requests name the scope and the goal, for example a full review before a release, or an authorization-only audit of one file. The agent will then run the three passes and report back.

• Review the functions in convex/ before I deploy.
• Audit the convex/ folder for authorization problems.
• Check my Convex mutations for missing auth checks and unsafe user IDs.
• Look at convex/messages.ts for performance issues like full table filters.

What the report looks like

The agent groups findings under Critical, Important and Suggestion. Each finding should state the issue, why it matters, and a suggested fix. The skill's rules require the agent to explain why a change is needed, not only what to change, so you can judge whether the advice fits your app.

Use the report as a checklist to work through, and re-run the review after you make changes.

What you need and what the skill does on your machine

You need a Convex project with code in a convex/ directory, and an AI agent that can read your project files, such as Claude Code. According to the skill's listing, it does not run scripts and does not use the network. It works by reading the code the agent has access to and applying the checklist.

Because the review is checklist-based, it can miss issues. Treat its output as a strong first pass, not a replacement for a human security audit on systems that handle sensitive data.

• Requires: a Convex project with a convex/ directory, and an agent that can read project files.
• Runs scripts: no. Uses network: no.
• Licence: MIT.

Tips for getting better reviews

Review the whole convex/ folder at once when you want cross-file checks such as ownership and index coverage, since a single file may not show the full picture. If you are new to Convex, read the Critical and Important findings closely, because they describe common anti-patterns you can learn from.

The skill is specific to Convex APIs. Do not use it on projects that do not use Convex, because the findings would be irrelevant.

• Scope the review to convex/ so the checks apply to the right code.
• Fix Critical findings first, then Important, then Suggestion.
• Re-run the review after changes to confirm the findings are resolved.