How to use the Convex Performance Audit agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions and reference files that an AI agent reads when a task matches the skill's description. This one is named convex-performance-audit and is built for Convex, a backend database and functions platform.

Once installed, the agent treats a slow or expensive Convex app as a performance problem to investigate. It gathers signals such as Convex insights, traces which functions read and write which tables, and then applies targeted fixes from reference guides on read amplification, write contention, subscription cost and execution limits. The skill is designed to prefer simple code over large restructuring unless the evidence justifies it.

Install the skill from a ZIP file

Download the ZIP of the skill from this page and unzip it. Then place the resulting folder in one of two locations, depending on how you want to use it.

For all of your projects on this computer, put it in ~/.claude/skills/. For one project only, put it in that project's .claude/skills/ folder. The skill's files include SKILL.md at the top level of the skill folder, so make sure the folder contains that file after unzipping.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

Prepare your Convex project and CLI

The skill needs a Convex project and the Convex CLI, run through npx convex. It also needs network access so that insights can be read from a deployment. If you want to audit production, you need deployment access or credentials for the target Convex project, because the --prod and deployment-name flags require them.

Two other skills are optional. convex-doctor can supply findings the agent may treat as hints, and convex-migration-helper is used for migration-heavy fixes.

• Convex project with the Convex CLI (npx convex)
• Network access to run insights against a deployment
• Deployment access or credentials for --prod or deployment-name flags
• Optional: convex-doctor and convex-migration-helper

Ask for an audit with a natural request

You do not need a special command to trigger the skill. Describe the symptom in plain language and the agent should match it to the skill's description. The skill is meant for slow features, insights findings, OCC conflicts, read amplification, high subscription counts, and functions near execution or transaction limits.

Naming the page or feature helps the agent scope the audit to one concrete user flow, which is the first thing the skill asks it to do.

• Our chat page feels slow to load. Audit its Convex queries for performance problems.
• Insights show high bytes read on the orders list. Find the cause and fix it.
• We are seeing OCC conflict errors when users update their settings. Investigate the mutations.
• Some of our mutations hit transaction size errors. Check the functions and suggest fixes.

What the agent checks during an audit

The agent first gathers signals, starting with the strongest available. If deployment health insights are already in the context, it uses them. If CLI insights are available, it runs npx convex insights --details, adding --prod, --preview-name or --deployment-name when needed. If the local Convex CLI is too old to support insights, it tries npx -y convex@latest insights --details before giving up. If no runtime signals exist, it audits from code and keeps its guardrails in mind.

It then routes the problem to a reference file. Hot paths with high bytes or documents read go to hot-path-rules.md. OCC conflicts and mutation retries go to occ-conflicts.md. High subscription counts go to subscription-cost.md. Timeouts and transaction size errors go to function-budget.md. The agent traces every read and write in the chosen flow and inspects sibling functions that touch the same tables, so that a fix is applied consistently.

• Gather signals from insights, dashboard or code
• Route to a reference: hot-path, OCC conflicts, subscription cost or function budget
• Trace every ctx.db read and write in the flow
• Fix sibling readers and writers of the same tables together
• Verify results are unchanged and no records are dropped

Know what the skill will not do

The skill is deliberately cautious. It says not to use it for initial Convex setup, auth setup or component extraction, or for pure schema migrations with no performance goal. It also advises against invented structural work, such as digest tables or document splitting, unless there is a measured signal, a clearly unbounded path or a known hot path.

For larger changes, such as introducing summary tables across several flows or reworking pagination across screens, the agent is told to stop and present options before editing. Small projects with modest traffic may be told to leave simple code alone.

• Not for initial setup, auth configuration or migrations without a performance goal
• Not for one-off micro-optimizations without a visible problem
• Large or migration-heavy changes are presented as options before any edit