Guide · Agent skill
How to use the Convex Component Update Checker agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convex-check-updates skill is an agent skill for Claude that checks a Convex app's pinned components against recommended versions and lists the ones that are out of date. It upgrades nothing until you approve, and then it works one component at a time, running typecheck and build checks after each step. This guide explains what agent skills are, how to install this one, how to ask for it in plain language, and what to watch for before you let it touch your code.
Convex Component Update Checkeropenclaw/clawhub · MIT Download the skill Quick start
- 1Install the skill. Unzip the convex-check-updates ZIP into ~/.claude/skills/ for personal use or .claude/skills/ in your project, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm prerequisites. Make sure Node.js, curl and git are installed, and that your project is a Convex app with typecheck and next build set up.
- 3Ask for a check. In your project, ask the agent to check your Convex components for updates. It will run the check script and list any stale components.
- 4Review the list. Look at each component's installed and current versions, summary and breaking flag before deciding anything.
- 5Approve one upgrade. Reply yes to the component you want to upgrade. Create a git commit or branch first if the upgrade is marked breaking.
- 6Let the gates run. The agent applies the migration steps and runs typecheck and build after each one. If a gate fails, it reverts and reports the failure.
- 7Run the smoke check. Run the smoke check the agent gives you, then repeat the process for the next stale component.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This one is named convex-check-updates and is described as checking the current app's pinned Convex components against recommended versions and upgrading them behind a build gate.
When the skill runs, the agent fetches a check script, compares your pinned component versions against recommended versions from the anteater registry, and reports which components are stale. Each stale entry is listed with its component name, installed version, current version, a summary and a breaking flag. The agent then asks you before changing anything.
- Lists stale components without modifying the project
- Upgrades only after an explicit yes from you, including for minor versions
- Applies each migration step, then runs the migration's gate commands
- Reverts and reports if a gate command fails
- Gives you a smoke check to run after each successful upgrade
Install the convex-check-updates skill
The skill is distributed as a ZIP file from the directory page. You can install it in one of two ways. For Claude Code, unzip it into your personal skills folder at ~/.claude/skills/ or into a project-level .claude/skills/ folder inside your repository. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
After unzipping, the folder should contain SKILL.md. The source lists SKILL.md as the only file in the package.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ in your project root
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Requirements before you run it
The skill depends on several tools and on your project being a Convex app. The check script is a downloaded .mjs file that runs with Node.js, so Node.js must be installed. The skill also uses curl to download the script and git for snapshots and reverts.
The skill needs network access to graceful-tiger-715.convex.site. Your project should already have a typecheck command and a next build setup, because the upgrade gate runs both.
- Node.js, to run check-updates.mjs
- curl, to download the script
- git, for snapshots and reverts
- Network access to graceful-tiger-715.convex.site
- A Convex project with typecheck and next build configured
Run the check to list stale components
Ask the agent to check your Convex components. Under the hood, the skill runs a download-and-run command from the project root. The output either reports that components are up to date, or lists stale components with a count.
Read the list before you approve anything. The breaking flag tells you which upgrades need extra care.
curl -fsSL https://graceful-tiger-715.convex.site/check-updates.mjs -o /tmp/cu.mjs && node /tmp/cu.mjsApprove upgrades one component at a time
When you say yes, the agent installs the new version, applies each listed migration step, and runs the gate commands. It delegates edits inside the convex/ folder to a convex-expert agent. If any gate command fails, the agent reverts with git checkout or by reinstalling the old version, then reports what happened so the app is never left half-migrated.
Each component is gated individually before the next one starts. Upgrades marked breaking need a commit or branch created first, so you have a clean point to return to.
- Breaking upgrades require a git commit or branch before the change
- Failed gates trigger a revert and a report
- The agent will not republish a live *.convex.app site without your confirmation
Run the smoke checks after each upgrade
After each successful upgrade, the agent gives you the smoke check defined for that migration. Run it yourself before moving on to the next component. The skill does not describe a smoke test beyond reporting the one in the migration data, so the exact check depends on the component.
What people use it for
- Listing outdated Convex components before a release so you know what needs attention
- Upgrading one Convex component on a Next.js app while keeping each change verified by typecheck and build
- Preparing a branch for a breaking component upgrade with a clear revert path
- Getting a checklist of smoke tests to run after each component changes
Frequently asked questions
Is the convex-check-updates skill free?
The skill is published under the MIT licence, which permits use, modification and redistribution. Check the licence file in the source repository for the full terms.
What do I need to run convex-check-updates?
You need Node.js to run the downloaded check-updates.mjs script, curl to fetch it, and git for snapshots and reverts. Your project must be a Convex app with a typecheck command and next build configured, and the machine needs network access to graceful-tiger-715.convex.site.
How do I install the convex-check-updates skill?
Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside your project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
Does the skill upgrade my components automatically?
No. It lists stale components first and asks for an explicit yes before touching anything, including minor version updates. It then upgrades one component at a time and gates each one.
Is it safe to run a script downloaded from the internet?
The skill fetches and executes check-updates.mjs from an external URL, so it is only suitable if you are comfortable running that code. Review the script yourself before approving the skill, and use a branch or commit so you can revert changes.
Does this work on projects that do not use Convex?
No. The workflow is built around Convex components, so it is not useful for other stacks.
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
This skill suits developers maintaining a Next.js app on Convex who want a checked list of stale components and upgrades done in small, verified steps. It is a poor fit for projects without Convex, for production apps where you cannot make a snapshot or review changes first, and for anyone who is not comfortable running a downloaded script from an external URL.
Download the skill