convex-self-heal Skill for Claude Code: What It Does and How to Install It

Makes Claude turn a Convex production error into a tested fix pull request for you to review and merge.

Installs: 38.3K; on skills.sh
Stars: 68; on GitHub
Updated: Oct 2026; last repo commit

This skill makes Claude run a loop from a production error to a proposed fix. It pulls a new error captured by Sentinel, triages it, finds the root cause with the Convex audit skills and repairs it on a branch. Before proposing anything it certifies the fix: a clean tsc --noEmit, a rehearsal on a preview seeded with a prod snapshot when schema or data is touched, and a replay of the failing input that must no longer fail.

SKILL.md says it never auto-merges or auto-deploys to prod, and you keep the merge button. Only fix classes you approve up front are prepared automatically. The default set is validator fixes, missing-index adds, ownership-check adds and non-destructive backfills. It needs Sentinel installed, and it offers to install it and stops if it is missing. Its folder holds only SKILL.md.

Good for

Convex teams with a production app who want errors triaged and fixed faster
Developers who want a fix PR with test evidence attached

Install convex-self-heal

Claude Code

Copy this prompt.

Install the convex-self-heal skill in Claude Code. Run this command:

npx skills add https://github.com/convex/agent-skills --skill convex-self-heal --skill convex-sentinel --skill convex-deploy-guard --skill convex-insights

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 hands work to convex-sentinel, convex-deploy-guard and convex-insights, so the first command installs them too. It also mentions convex-advisor, convex-reviewer, convex-authz, convex-expert, convex-env and convex-migrate-rehearse 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-self-heal in Claude Code or $convex-self-heal 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. This skill works on your project folder, so this page offers no Claude app upload route.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

Production error → triaged, root-caused, repaired, and certified (tsc + rehearsal + reproduce-then-gone) fix PR for a human to merge — then confirm the error stops recurring. Never auto-merges.

Sections in SKILL.md

Workflow
Rules

Key facts

Author: Convex (GitHub organisation convex; the vendor's own repo)
License: Apache-2.0 (stated in the README and the LICENSE file)
Installs on skills.sh: 38,268 (Nov 2, 2026)
GitHub stars: 68 for the whole convex/agent-skills repo (Nov 2, 2026)
Last repo commit: Oct 29, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: warn
What it includes: 1 file: SKILL.md (the repo tree lists nothing else in the folder)
Part of: The convex/agent-skills repo: 33 skill folders in the tree. The README names 6 skills, and this one is not among them

What it includes

deploy-guard classifies the deployment, and you approve which fix classes may be prepared
Read · Guard and set the scope
Needs Sentinel; if it is missing, offers to install it and stops
Read · Require capture
Reads it from the Sentinel table through the MCP, then sorts it: transient, config or code
Transient blips get no PR. Config errors go to the env skill, and Claude never guesses a secret.
Network · Triage the error
Runs insights, advisor, reviewer or authz on the failing function, and stops if unclear
Network · Find the root cause
Applies the fix with the finding's fix skill, never on prod directly
Runs code · Repair on a branch
Checks tsc --noEmit, a rehearsal for schema changes, an error replay and no new finding
A fix that fails any applicable check is reported as "attempted, could not certify".
Runs code · Certify the fix
Opens a PR or a diff with the evidence, the original error and a reversibility note
Try: “Look at the latest prod error and prepare a certified fix”
Write · Propose, never merge
After you merge, deploys through deploy-guard consent and checks the error stops recurring
The check reads the Sentinel table and logs, not insights.
Runs code · Promote and confirm
Prepares only pre-approved fix classes and logs every action to an append-only record
Write · Bound and log

From the official docs

Permissions

High risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It reads production and proposes production changes
The loop works from prod errors and ends with a promote after you merge. SKILL.md gates the promote with deploy-guard's fresh consent and says it never auto-merges. Read each step before you approve it. github.com
Certification can use a copy of prod data
For schema or data fixes it runs migrate-rehearse, which exports a prod snapshot and imports it into a preview. Treat that snapshot as sensitive and delete it afterwards. github.com
Pre-approved fix classes run without a per-fix prompt
Fix classes you approve in step 1 are prepared automatically, though never merged. Keep that list short. github.com
The Convex MCP server limits production access by default
The Convex docs say the MCP server is safe by default: in production deployments agents cannot access PII and can only perform read-only operations. Write access and PII reads on production need --dangerously-enable-production-deployments or --cautiously-allow-production-pii. docs.convex.dev

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	SKILL.md defines no read-only mode. It says the loop reads prod and proposes prod changes, and never auto-merges.
Sign-in and keys	SKILL.md names no credentials. It says to hand config errors to the env skill and never guess a secret.
Scopes	Reads production errors captured in your own deployment Edits code on a branch and opens a PR or diff May export a prod snapshot and import it into a preview during certification Promotes a merged fix to prod after deploy-guard consent

Questions

What does convex-self-heal do?

It makes Claude take a production error from your Convex app, work out the cause, write a fix on a branch, test the fix and open a pull request. It then checks that the error stops after you merge and deploy.

Does it merge or deploy by itself?

SKILL.md says it never auto-merges or auto-deploys to prod. You keep the merge, and promotion goes through deploy-guard's fresh production consent.

What does it need?

Sentinel for error capture, which convex-sentinel sets up, and access to the Convex MCP tools to read the errors. For schema or data fixes it uses migrate-rehearse, which needs a Preview Deploy Key for previews. The install box lists the MCP server command from the Convex docs.

Which kinds of fixes will it prepare on its own?

Only classes you approved at the start. SKILL.md gives the default-safe set as validator fixes, missing-index adds, ownership-check adds and non-destructive backfills. Anything destructive, security-sensitive beyond an added check, or unclear is left to you.

How do I install it?

Use the install box at the top of this page. The first command installs convex-self-heal with convex-sentinel (capture), convex-deploy-guard (consent) and convex-insights (first root-cause pass). SKILL.md also routes to convex-advisor, convex-reviewer, convex-authz, convex-expert, convex-env and convex-migrate-rehearse depending on the error; install those separately, or use the All command, for the full loop. Run it with /convex-self-heal in Claude Code or $convex-self-heal in Codex.

Is it safe?

It reads production errors, can import a prod snapshot into a preview during rehearsal, edits code on a branch and opens a PR. Keep the approved fix classes narrow and read every certification result before merging. Our advice: start with one low-risk error.

How does it differ from Sentry or Datadog?

SKILL.md claims those tools can go from error to a draft PR but treat the backend as opaque and stop at the merge gate with an unverified diff. Its pitch is that Convex can rehearse the fix on a preview of your own deployment before anyone reviews it.

Is it official?

It is in the convex/agent-skills repo under the Convex GitHub organisation, which is the vendor's own repo.

Information

updated Nov 2, 2026

Repository: convex/agent-skills
Folder: skills/convex-self-heal

convex/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

convex/agent-skills README · github.com
skills CLI commands · github.com
Convex docs: Agent Skills · docs.convex.dev
convex-self-heal SKILL.md · github.com
Convex docs: MCP server · docs.convex.dev