Guide · Agent skill
How to use the Convex Spend Preview agent skill (convex-cost)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-cost skill is an agent skill for Convex, a hosted backend database platform. It helps an agent estimate and explain what a Convex app will cost to run, by reading your deployment's usage insights and showing which functions read the most data across how often they are called. This guide covers what the skill does, how to install it, how to trigger it with plain requests, and what it needs before it can work.
Convex Spend Previewopenclaw/clawhub · MIT Download the skill Quick start
- 1Download the ZIP. Download the convex-cost skill ZIP from this page.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project.
- 3Or upload in Claude. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- 4Check your requirements. Confirm you have Convex MCP server access with user authentication and a Convex project with a dev or prod deployment; insights need a cloud deployment.
- 5Ask a cost question. Describe the cost concern in plain language, such as which functions drive your bill or whether the app will get expensive at scale.
- 6Review the ranked drivers. Read each driver's evidence, growth shape and cheapest fix in the report.
- 7Confirm any paid action. Reply with an explicit yes only after reviewing the stated price and recurrence for any metered step.
What is an agent skill and what does convex-cost make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent (such as Claude) loads when a task matches the skill's description. The skill tells the agent how to approach that task, step by step.
convex-cost focuses on spend. It reads the deployment's own bytes-read and documents-read evidence, attributes that usage to the functions causing it, and projects how each cost driver grows as data and traffic increase. For each driver it names the cheapest fix, such as adding an index instead of scanning a whole table, and it asks for explicit confirmation before any paid action.
- Ranks functions by data read per call multiplied by call volume, since either factor alone can mislead.
- Shows the growth shape of each top cost driver, for example that a full-table scan grows with the table.
- Suggests the cheapest fix per driver, such as an index with .withIndex, .paginate or .take, or an aggregate component for counts.
- Requires explicit yes before anything metered happens, such as a domain purchase, cloud provisioning or plan change.
Install the convex-cost skill
Download the ZIP for the skill from this page. The skill is distributed as a folder whose main file is SKILL.md.
Option 1, personal install: unzip the download into ~/.claude/skills/ so the skill is available across your projects.
Option 2, project install: unzip the download into the .claude/skills/ folder inside a specific project so it applies only to that project.
Option 3, Claude apps: upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What you need before using it
The skill depends on Convex's MCP tools and insights data, so it will not help with apps that are not built on Convex. You need Convex MCP server access with user authentication. Insights are only available for cloud deployments.
You also need a Convex project with deployments to read, either dev or prod. The skill reads from these deployments, so the agent must be able to query them.
- Convex MCP server access with user authentication.
- A Convex project with at least one deployment (dev or prod).
- Cloud deployments for insights data.
How to trigger the skill with natural requests
You do not need a special command. Describe the cost question in plain language and the agent will load the skill when the request matches its description. Good requests name the outcome you care about: a bill, growth, or a specific function.
The skill announces which deployment it is reading before it starts, and it only reads. Cost reads are read-only over dev and prod.
- What is driving my Convex bill this month?
- Which functions read the most data in my Convex app?
- Will this Convex app get expensive as the table grows to a million rows?
- Review my Convex query patterns for cost before we launch.
- Estimate the cost of adding this feature before I deploy it.
Examples of what you get back
A typical report lists the current cost drivers in ranked order. Each driver includes its evidence from insights, its growth shape, and its fix. The skill gives shapes rather than exact dollar totals, because Convex pricing changes and depends on plan.
If there is no usage yet, the skill estimates from query shapes instead. For example, a .collect() on a table that is expected to grow is a future cost even with no traffic today.
- Driver: a function reads a whole table on every call. Growth: cost rises with table size. Fix: add an index and use .withIndex.
- Driver: a cheap function called very often. Growth: cost rises with call volume. Fix: cache a hot read or reduce calls.
- Bottom line example: spend dominated by one list query reading the full table on every call; indexing it would substantially reduce the cost.
Safety notes: scripts and network access
This skill does not run scripts. It does use the network, because it queries Convex MCP tools and live deployment insights. Expect the agent to read live usage data from your dev or prod deployments.
Any paid action, such as a domain purchase, cloud provisioning or plan change, must be priced and confirmed by you before it happens. The skill is designed never to make a paid change as a side effect.
- No scripts are run by this skill.
- Network access is used to read deployment insights and tables through Convex MCP.
- Paid actions require your explicit yes after the price and recurrence are stated.
Tips for getting useful results
Name the deployment you care about, and say whether you want an estimate for current traffic or for planned growth. Ask for the growth shape, not a dollar figure, and use the Convex pricing page for absolute prices.
When the skill recommends a fix, take the finding to a Convex coding or advisor skill to make the actual change. convex-cost identifies the driver and the fix; it does not make the code change itself.
- Specify dev or prod so the agent reads the right deployment.
- Ask about growth, for example 'what happens at 1M rows'.
- Use the Convex pricing page for exact figures, since prices depend on plan.
- Pair the result with a performance or code-review skill to apply the fix.
What people use it for
- Finding which list or search function reads the whole table on every page load before traffic grows.
- Planning for growth by seeing how a scan's cost scales from a thousand rows to a million.
- Reviewing query patterns for cost before launching a new Convex feature.
- Investigating an unexpected bill by ranking functions by data read times call volume.
- Deciding whether to add an index, pagination, or a cache before scaling.
Frequently asked questions
How do I install the convex-cost skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to use convex-cost?
You need Convex MCP server access with user authentication and a Convex project with a dev or prod deployment to read. Insights are only available for cloud deployments.
Is convex-cost free and what is its licence?
The skill is published under the MIT licence, as stated on this page. The source does not describe any paid tier for the skill itself, but Convex's own hosting and usage are billed by Convex, so check Convex's pricing page for those costs.
Does convex-cost give me exact dollar figures for my Convex bill?
No. It deliberately gives growth shapes and points to Convex's pricing page rather than computing prices, because pricing changes by plan. It shows which functions drive usage and how that usage scales.
Can convex-cost be used on apps that are not built on Convex?
No. The workflow depends on Convex's MCP tools and insights data, so it only applies to Convex apps.
Does convex-cost change my code or run scripts?
It does not run scripts and it is read-only over dev and prod deployments. It recommends the cheapest fix for each driver and passes it to a Convex coding or advisor skill to make the change.
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-cost if you run a Convex app and want to know which functions drive usage before a bill surprises you, or before traffic and data grow. Pick something else if you need exact dollar totals, if your app is not on Convex, or if you have no cost concern and only want a general code review.
Download the skill