Guide · Agent skill
How to use the Convex Feature Verification agent skill (convex-verify)
Updated · written with AI from the project's own documentation and checked against our catalogue data
convex-verify is an agent skill: a folder of instructions (a SKILL.md file) that teaches an AI coding agent a specific, repeatable workflow. This one makes the agent prove that a Convex feature you just built actually works, including whether outsiders are correctly refused. It is aimed at developers building Convex apps who want evidence that permissions and data scoping hold, not just that the code compiles. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check in its results.
Convex Feature Verificationopenclaw/clawhub · MIT Download the skill Quick start
- 1Download and unzip. Download the convex-verify ZIP from this page and unzip it so the folder contains SKILL.md.
- 2Place the skill folder. Copy the convex-verify folder into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ for one project. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm prerequisites. Make sure Node.js and npm are installed and that your project is a Convex project.
- 4Ask for a feature proof. Describe the Convex function you built and who should and should not be allowed to call it.
- 5Let the agent set up convex-test. The agent adds convex-test, vitest and @edge-runtime/vm if needed and writes a vitest.config.ts using the edge-runtime environment.
- 6Run the tests. The agent runs npx vitest run and reports every positive and negative assertion.
- 7Act on failures. If a negative check fails, treat it as a possible access-control bug and fix the function, not the test.
What is an agent skill, and what does convex-verify make the agent do?
An agent skill is a set of instructions that an AI agent loads when a task matches the skill's description. The skill tells the agent how to approach that task step by step.
convex-verify covers one job: proving a specific Convex query, mutation or action behaves correctly. The agent identifies the feature you built, seeds realistic test data, calls the feature as the owner, as a different logged-in user, and as an anonymous caller, then checks the results. The negative cases are the important part: a caller who should be refused must be refused, and a list must contain only the caller's own rows. The checks run in-process with the convex-test library, so no live Convex deployment is needed.
If a check fails, the skill reports it rather than editing the test to make it pass. A failed refusal check usually points to a real access-control bug in the function.
Install the convex-verify skill from the ZIP
Download the convex-verify ZIP from this page. The package contains one file, SKILL.md. Unzip it so the folder is named convex-verify and contains SKILL.md.
For a personal install that applies to all your projects, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/convex-verify/SKILL.md
- Project install: .claude/skills/convex-verify/SKILL.md inside your project
~/.claude/skills/convex-verify/SKILL.mdCheck what your project needs before you start
The skill needs Node.js and npm, because it runs tests with npx vitest run. Your project should be a Convex project. The skill expects convex-test, vitest and @edge-runtime/vm as dev dependencies. It will install or ask for these if they are missing.
The skill also authors a vitest.config.ts that uses the edge-runtime environment and inlines convex-test. Without this configuration, convexTest(schema) fails at runtime, so the skill sets it up as part of the workflow rather than leaving it to you.
If your project already has a test setup, the skill is meant to reuse it rather than replace it.
- Node.js and npm
- A Convex project
- Dev dependencies: convex-test, vitest, @edge-runtime/vm
- A vitest.config.ts using the edge-runtime environment (the skill writes this)
Trigger the skill with a natural request
You do not need a special command. Describe the feature and what should be true about it. The agent should match your request to the skill's description and follow its workflow.
Be specific about the function and the intended rules. The skill asks one focused question if the expected behavior is unclear, because it will not guess the contract.
- "Prove that only the owner can cancel an order in convex/orders.ts. Other users and logged-out callers should be refused."
- "Verify that the notes list query returns only the signed-in user's notes."
- "Test the new shareDocument mutation as the owner, another user and an anonymous caller."
Read the results: what passed and what failed
After the run, the agent should list each positive assertion (the owner got the expected result) and each negative assertion (an outsider was refused, or a list excluded another user's rows) that passed.
Pay close attention to any failed assertion. The skill treats a failed negative test as a real defect found before shipping, and it hands the fix to the access-control or correctness work rather than changing the test. Do not accept a green run that was reached by weakening an assertion.
- Positive: the owner gets the expected rows or the expected change
- Negative: a wrong user or anonymous caller is refused
- Data scope: a list never includes the second user's rows
- Failures: report the exact failing call as evidence
Tips for getting useful results
Point the skill at one feature at a time. It is built to verify a specific exported function or a small set of them.
Seed through your app's own functions where possible, so the test data passes the same validators a real user would hit.
Use the verification for permissions and data scope. For a general test framework setup, use a separate testing capability; the skill itself says that job is outside its scope.
- Name the exact function file and export
- State who should be allowed and who should be refused
- Keep a passing run as evidence only for the cases it covers
What people use it for
- Confirm that only a project's owner can edit or delete a record in a Convex mutation.
- Check that a notes or tasks list query returns only the signed-in user's rows.
- Verify that an anonymous caller is refused by a protected action before you ship.
- Add negative authorization tests to an existing vitest suite for Convex functions.
Frequently asked questions
How do I install the convex-verify skill?
Download the ZIP from this page and unzip it so the convex-verify folder contains SKILL.md. Put it in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
Is convex-verify free to use?
The skill is listed under the MIT licence. This page does not state pricing for anything beyond the skill itself, so check the licence file in the source repository for the full terms.
What do I need installed to use it?
You need Node.js and npm, a Convex project, and the dev dependencies convex-test, vitest and @edge-runtime/vm. The skill can install or request these, and it writes the vitest.config.ts it needs.
Does it need a live Convex deployment?
No. The skill runs its checks in-process with the convex-test library, so tests do not need a deployed backend.
Does convex-verify run scripts or use the network?
It runs scripts, since it executes npx vitest run. The listing states that it does not use the network.
Can it replace a security review?
No. It checks the cases it writes tests for, not every possible attack, so coverage depends on the scenarios chosen. It is a way to gather evidence for specific permission rules.
How is it different from a general testing skill?
convex-verify targets one built Convex feature and its negative authorization cases. Setting up a test framework for a whole project is a separate job that the skill says belongs to a different test capability.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use convex-verify if you build Convex apps with vitest and want tests that prove outsiders are refused and data stays scoped to its owner. Pick something else if you need a general test framework for a project, use a non-Convex backend, or want a full security review, since this skill only covers the cases it tests.
Download the skill