How to use the Convex Authz Auditor agent skill (convex-authz)

What is an agent skill, and what does convex-authz make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI coding agent loads when a request matches the skill's description. convex-authz is one such skill, and its SKILL.md is the only file it ships.

When it runs, the agent looks for four shapes of access-control bug in a Convex app: functions that trust a user ID passed in by the client (identity-from-arg), reads and writes with no per-document ownership check, public queries that leak sensitive fields when given a client-supplied id, and writes into a parent or container the caller does not own.

• Runs a pattern-based scan over the convex/ directory first, reporting file, line and which shape matched.
• Adds requireIdentity and requireOwner checks where the app has a proper auth setup.
• Runs the TypeScript compiler to confirm the edits.
• On an app with no auth foundation, converts privileged functions to internal-only and tells you to set up auth first.

Install convex-authz from the ZIP

Download the convex-authz ZIP from this page and unzip it. You should end up with a convex-authz folder containing SKILL.md. Put that folder in one of these locations:

• Personal skills folder: ~/.claude/skills/
• Project-only: the .claude/skills/ folder inside your Convex project
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need to type a command. The skill's description lists trigger phrases, so ask for what you want in plain language. The source names these triggers: 'secure my app', 'audit auth/authz' and 'who can access this data'.

The skill is designed to skip when the project has no convex/ directory, so point it at a Convex project.

• "Secure my app" in a project that contains convex/
• "Audit auth/authz for this backend"
• "Who can access this data?" when you are looking at a table or query
• Ask for the four shapes by name if you want a targeted review of ownership checks

What the skill needs before it runs

Check these requirements first. The skill depends on them to do its work correctly.

For a scan and report, you need a Convex app with a convex/ directory and TypeScript. For the verification step, the project's typecheck setup must work, using npx tsc --noEmit or the project's typecheck script.

For full hardening, the source says you need an auth.config.ts with a provider and a users table keyed to the auth subject. Without both, the skill will not add enforcement.

• A convex/ directory and TypeScript
• A working typecheck (npx tsc --noEmit or the project's script)
• An auth.config.ts with a provider, plus a users table keyed to the auth subject, for full hardening

What happens on an app without auth set up?

This is the most important limit to understand. The skill's workflow checks for an auth foundation before adding any ctx.auth enforcement. If the foundation is missing, adding those checks would fail silently, because ctx.auth.getUserIdentity() returns null on such an app.

In that case the skill converts flagged privileged functions from public query or mutation to internalQuery or internalMutation, which removes public reachability. It then tells you to set up auth first and re-run convex-authz to add per-user ownership checks.

• Expect an internalize-and-defer diff rather than ownership checks on an app with no auth.
• Internal functions are not callable from clients, so check that your frontend does not call the converted functions directly.

Read the report and the diff

The skill reports findings grouped by the four shapes, with file and line numbers, and explains why each one is exploitable. It should also show the concrete diff it applied, not just describe the fix.

After the edits, the skill re-runs its scan. The source says a clean result means 0 remaining hits. Review the diff yourself before you deploy, because the scan is regex-based and can miss or misflag code.

• Check each reported file:line against your own logic.
• Confirm that ownership comparisons use the right value: the source warns that comparing an Id<"users"> field to identity.subject never matches.
• Run your own tests after the typecheck passes.