Guide · Agent skill
How to use the Convex Live Deployment Advisor agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-advisor skill is an agent skill for Convex developers. It makes an AI agent read your live Convex deployment's last 72 hours of health data, such as functions hitting read limits or repeatedly retrying writes, and trace each event back to the code that caused it. This guide explains what an agent skill is, how to install convex-advisor, how to ask for it in plain language, and what to check before you trust its findings.
Convex Live Deployment Advisoropenclaw/clawhub · MIT Download the skill Quick start
- 1Download and unzip. Download the convex-advisor ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
- 2Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 3Log in to Convex. Make sure you are logged in to Convex as a user and that the official Convex MCP server is available.
- 4Confirm the deployment. Choose a cloud dev or prod deployment with about 72 hours of traffic. The agent announces which deployment it will read.
- 5Ask for a review. Describe the goal in plain words, such as finding functions that hit read limits or write contention.
- 6Review ranked findings. Read the findings, each with runtime evidence, the file and line root cause, and a proposed fix.
- 7Confirm fixes. Approve the fixes you want. The agent applies them only after confirmation and can re-check insights later.
What an agent skill is and what convex-advisor makes the agent do
An agent skill is a folder of instructions, bundled with any supporting files, that an AI agent such as Claude loads when a request matches the skill's purpose. The skill's main file is SKILL.md. Here the file is named SKILL.md, and it sets out the workflow the agent follows.
Instead of guessing from static code, convex-advisor reads the official Convex MCP insights tool, which returns typed 72-hour health events for each function. These include documentsReadLimit and bytesReadLimit (hard limit hits), documentsReadThreshold and bytesReadThreshold (approaching a limit), and occFailedPermanently and occRetried (write contention). For each event the agent reads the flagged function's code, names the likely cause, and reports ranked findings with evidence and suggested fixes.
The skill does not change anything on its own. Fixes are applied only after you confirm.
Install convex-advisor from the ZIP
Download the ZIP of the skill from this page and unzip it. You can install it in one of two places. For a personal install available in all your projects, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the project's .claude/skills/ folder. Either way, the result should be a convex-advisor folder containing SKILL.md.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/convex-advisor/
- Project install: .claude/skills/convex-advisor/ inside your project
- Claude apps: Settings → Capabilities → Skills
~/.claude/skills/Set up what the skill needs before you run it
The skill needs several things to work. You must be logged in to Convex as a user, and the official Convex MCP server must be available to the agent. Your deployment must be a cloud dev or prod Convex deployment with roughly 72 hours of traffic. The agent also needs access to your project's Convex function source code, because it reads that code to find root causes.
- A Convex account, logged in as a user
- The official Convex MCP server available to the agent
- A cloud dev or prod Convex deployment with about 72 hours of traffic
- Access to the project's Convex function source code
Trigger the skill with natural requests
You do not need a special command. Describe what you want in plain language, mentioning performance, cost, read limits, or write contention. Good requests name the thing you care about, such as slow queries or a function that keeps retrying writes.
The agent first identifies which deployment it will read and tells you. For production it reads insights and logs in read-only mode and does not enable any mutating access.
- Check my Convex deployment for functions hitting read limits in the last 72 hours.
- Find out why writes to my counters keep retrying.
- Which of my Convex queries are reading the most data, and how do I fix them?
- Review live performance and cost on my prod deployment and rank the findings.
Read the findings report
The report ranks findings by severity. Each finding includes a one-line piece of runtime evidence, the code-level root cause with a file and line reference, and the concrete fix along with which capability would apply it. Severity follows the event type: limit hits and permanent write-contention failures are high, while threshold warnings and retried writes are medium.
If the deployment has no usable insight data, the agent says so and offers a different review instead of inventing findings.
- Evidence: the runtime event, for example a function reading a large volume of data from one table many times
- Root cause: the file and line, and the mechanism, such as an unindexed filter or a missing pagination
- Fix: the proposed change and whether it is applied on your confirmation
- Verification: after traffic builds up, the agent can re-check insights to see whether the trend improved
Safety notes: scripts and network access
This skill does not run scripts. It does use the network, because it queries Convex through the MCP server to read deployment status, insights, table stats and function specs, and logs. The advisory pass is read-only by design: it never mutates a deployment and never enables production mutation flags.
Security and authorization reviews are outside this skill. Those are handed to other skills, and the advisor only reports performance, cost, and health.
- Runs scripts: no
- Uses network: yes, through the Convex MCP server
- Read-only on deployments; changes only after you confirm
- Authorization findings are routed to convex-authz, style to convex-reviewer, and error triage to sentinel
What people use it for
- Finding queries that call collect() or filter without an index and read far more data than needed
- Diagnosing a shared counter or status field that causes repeated write retries under load
- Spotting a cron job or function that keeps failing and tying the failure to its code
- Ranking performance and cost issues on a production deployment before a launch review
Frequently asked questions
Is the convex-advisor skill free to use?
The source for this skill is published under the MIT licence. The source does not state any price, so check the directory page for current terms. Using the skill still requires a Convex account and access to the Convex MCP server.
What do I need to use convex-advisor?
You need a Convex account logged in as a user, the official Convex MCP server available to the agent, a cloud dev or prod deployment with roughly 72 hours of traffic, and access to your project's function source code. The skill also needs network access.
Why does the skill report nothing for my project?
The insights data is only available on cloud dev or prod deployments when you are logged in as a user, and it needs about 72 hours of traffic. Preview deployments and deploy-key contexts do not provide it. In those cases the skill reports that no data is available instead of inventing findings.
Does convex-advisor fix my code automatically?
No. It reports findings with evidence and suggested fixes, and it applies changes only after you confirm. The advisory pass never mutates a deployment.
Can convex-advisor check security or authorization issues?
No. Authorization reviews are handed to the convex-authz skill. convex-advisor is limited to performance, cost, and health findings, and style issues go to convex-reviewer.
How does it compare with a general code review skill?
convex-advisor bases its findings on real runtime events from the last 72 hours, such as read limit hits and write retries, and then traces them to code. A static review skill such as convex-reviewer checks code style and idioms without live traffic data.
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-advisor if you run a production or cloud dev Convex app and want to find slow, costly, or contended functions based on real traffic. Skip it if your project has less than about 72 hours of traffic, runs on preview or deploy-key contexts, or needs a security review. Use a static review skill instead when you want style and idiom feedback without live data.
Download the skill