Convex Advisor skill for Claude Code: find slow and costly functions from live data
Makes Claude read your Convex deployment's last 72 hours of health events, trace each one to its code, and report fixes.
- Installs
- 38.4K
- on skills.sh
- Stars
- 68
- on GitHub
- Updated
- Oct 2026
- last repo commit
Claude first names the deployment it is reading, then uses the official Convex MCP: status to pick the deployment, insights for the 72-hour events, tables for schemas and row counts, and functionSpec for the function list. For each event it reads the flagged function, finds the cause in the code, and proposes a fix such as an index, .take(n), pagination or a sharded counter.
It reports findings ranked by severity, each with one line of runtime evidence, the file and line, and the fix. SKILL.md says it applies fixes only after you confirm, and that it must not invent findings: if insights returns nothing, it says so and offers convex-reviewer. The skill folder holds one file, SKILL.md.
Good for
- Convex developers hitting read limits or write conflicts
- Teams trying to cut Convex read volume and cost
- Apps already running on a cloud dev or prod deployment
Install convex-advisor
Claude Code
- 1
Copy this prompt.
Install the convex-advisor skill in Claude Code. Run this command: npx skills add https://github.com/convex/agent-skills --skill convex-advisor --skill convex-deploy-guard Then check that it loaded and tell me how to use it.
- 2
Paste it into Claude Code. It shows the change and asks before running it.
Requires Node.js.
SKILL.md runs convex-deploy-guard steps 0 and 1 first, so the first command installs it too. It hands findings to convex-authz, convex-reviewer, convex-sentinel as optional hand-offs; install those separately if you want them. Convex's docs say the skills CLI installs skills into .agents/skills/ in your project. The "All Convex skills" command installs every skill in the repo, which has 33 skill folders. One of them, convex-improve-convex-plugin, is listed in the Convex docs as sending your coding session's transcript to the Convex team. Run this skill with /convex-advisor in Claude Code or $convex-advisor in Codex, or let the agent pick it when the task fits. This skill reads your deployment through the official Convex MCP server, which is not part of the skills. Add the server command to your client's MCP settings; the Convex docs also describe an official plugin that starts it for you.
Built from the package data we hold. Not yet tested by us.
What's in the skill
When it loads
Read the Convex deployment's 72h insights (read limits, OCC contention), root-cause each event in code, report evidence-backed perf/cost findings with fixes.
Sections in SKILL.md
- Workflow
- Rules
Key facts
- Installs on skills.sh
- 38,421 (Nov 2, 2026)
- GitHub stars
- 68 (Nov 2, 2026)
- Last commit to the repo
- Oct 29, 2026
- What installs
- 1 file: SKILL.md
- skills.sh audits
- Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes
Names the deployment being read before it reads anything
It follows convex-deploy-guard steps 0 and 1. Reading insights and logs on prod is allowed read-only, and it never enables mutating prod access for an advisory pass.
Read ·
Guard the targetCalls status, insights, tables and functionSpec
insights is only available on cloud dev or prod deployments when you are signed in as a user, not on previews or deploy-key contexts, and it needs about 72 hours of traffic.
Network ·
Gather from the Convex MCPReads the flagged function and names the line and the mechanism
Read-limit events point to .collect(), unindexed .filter() or missing pagination. Write-contention events point to read-modify-write hotspots such as shared counters.
Files ·
Root-cause each eventLimit hits and permanent write failures rate high, thresholds and retries medium
Each finding has a one-line evidence line, the code cause and the fix.
Rank by severityApplies a fix only after you confirm, then re-checks insights later
It routes authorization issues to convex-authz, code style to convex-reviewer and error triage to sentinel.
Write ·
Report and offer fixes
From the official docs
Permissions
Low risk
Claude reads your live Convex deployment through the MCP server, and applies code fixes only after you confirm. Keep the MCP on a non-prod deployment unless you need prod insights, and leave the prod-change flag off.
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only modeHow to turn it on
Watch out for
It needs the Convex MCP, which can reach prod
The MCP is safe by default on prod, per the Convex docs, and uses your global Convex login unless you set a deploy key, so it can reach every project your account can. Do not add the flag that allows prod changes for an advisory pass. docs.convex.dev
Fixes edit your code after you confirm
SKILL.md applies fixes only on confirmation. Review each diff, since a fix may add an index or change a query. github.com
It refers to a findings file that is not in the repo
SKILL.md says to emit findings per specs/finding.schema.json. The repo has no specs folder, so what you see is the ranked report. github.com
Security advisories
No published security advisories as of Nov 2, 2026.
Technical details
| Turning on read-only | SKILL.md says an advisory pass never mutates any deployment. Our advice: start the MCP with the run and env tools disabled (--disable-tools) to enforce it. |
|---|---|
| Talks to | Your Convex deployment, through the Convex MCP |
| Scopes |
|
Questions
How do I install convex-advisor?
Use the install box above, and add the Convex MCP server to your client too, since the skill reads your deployment through it. The first command also installs convex-deploy-guard, which SKILL.md runs first to name the deployment. SKILL.md hands findings to convex-authz, convex-reviewer and convex-sentinel; those are optional and install separately. Run the skill with /convex-advisor in Claude Code or $convex-advisor in Codex.
What data does it read from my deployment?
The 72-hour insights events, your table schemas with row counts, the list of functions, and function logs when it checks repeated failures. Per the Convex MCP docs, insights, tables and functionSpec are non-PII read-only operations that work on production by default. Logs are a PII read operation that is off for production unless the MCP is started with --cautiously-allow-production-pii.
Why did it return no findings?
SKILL.md says insights needs about 72 hours of traffic and works only on cloud dev or prod deployments when you are signed in as a user. When there is nothing, Claude should say so and offer convex-reviewer instead of making findings up.
How is it different from convex-insights?
convex-advisor roots health events in code and owns the performance and cost fixes. convex-insights, per its SKILL.md, answers questions about logs and health, and hands performance and cost fixes to convex-advisor.
Is it safe?
It reads your deployment through the Convex MCP and your function code, and applies code fixes only after you confirm. Our advice: keep the MCP scoped to a non-prod deployment unless you need prod insights, and leave the flag that allows prod changes off, as SKILL.md does for an advisory pass.
Is it official?
Yes. It is in Convex's own agent-skills repo, and Convex's docs list it among the agent skills Convex provides.
Does it work in the Claude app?
The README and Convex docs name Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf and Codex. They do not name the Claude app, and this skill works on a local project, so we list no Claude app install.
Information
updated Nov 2, 2026
- Repository
- convex/agent-skills
- Folder
skills/convex-advisor
Sources
Docs, issue trackers and discussions this page is built from.
Show all 5Hide
- convex/agent-skills README · github.com
- Convex docs: Agent Skills · docs.convex.dev
- Convex docs: MCP server · docs.convex.dev
- convex-advisor SKILL.md · github.com
- convex-insights SKILL.md · github.com