How to use the Convex self-healing fix loop agent skill

What does the skill make the agent do?

The skill describes a gated loop with a fixed human checkpoint. The agent reads production errors, sorts them into transient, config, or code and schema defects, and only works on the last category. For a real defect it finds the root cause, writes a fix on a branch rather than on production, and tests that fix before proposing it.

Certification has three parts in the source: a clean tsc --noEmit type check, a rehearsal through migrate-rehearse on a preview seeded with a production snapshot when the fix touches schema or data, and a reproduce-then-confirm-gone test that replays the triggering input and checks the failure no longer happens. A fix that fails any applicable check is reported as attempted but could not certify, and is not proposed as done.

After a human merges and the change deploys, the agent checks the sentinel table and logs to confirm the error stops recurring. If it comes back, the loop reopens with the new evidence.

• Triage: transient blips are retried or ignored, config errors go to environment handling, and code or schema defects enter the repair loop.
• Root cause: the agent must produce evidence such as the stack and the reproducing input. If the cause is unclear, it stops and reports.
• Proposal: the pull request includes the fix, the certification results, the original error, and a reversibility note.
• Promotion: the skill never auto-merges or auto-deploys to production. The human keeps the merge button.

What do you need before you install it?

The skill is built for a Convex deployment that already has the sentinel error-capture skill installed. The source says the loop stops if capture is absent, because there is nothing to heal without it. The workflow also expects the official Convex MCP for querying the sentinel table, logs, and preview deployments, plus the TypeScript compiler (tsc) for the type-check step.

You also need Git and pull request access to the repository being fixed. The workflow refers to several companion skills: deploy-guard, migrate-rehearse, convex-insights, convex-advisor, convex-reviewer, convex-authz, convex-expert, and convex-test. Check that these are available before you rely on the full loop.

• A Convex deployment
• The sentinel error-capture skill installed
• Official Convex MCP access
• TypeScript compiler (tsc)
• Git and pull request access to the repository
• The companion skills listed above

How do you install the convex-self-heal skill?

Download the skill ZIP from this page. The skill's listed file is SKILL.md, so the ZIP should contain that file. Unzip it so the skill folder ends up in one of two places: ~/.claude/skills/ for your user account, or .claude/skills/ inside a specific project if you want the skill limited to that project.

In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ in the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with natural requests?

The source does not list fixed trigger phrases, so describe what you want in plain language. The skill's description covers production errors, triage, root cause, repair, certification, and pull requests, so requests that name those things are the most likely to match.

When you ask, state the error or the function involved, and say whether you want a proposal or only a diagnosis. Set the boundaries early, because the workflow starts by agreeing on which classes of fix the agent may prepare on its own.

• Look at the recurring production error in the payments function and prepare a fix PR if you can certify it.
• Triage today's production errors in my Convex deployment and tell me which are transient and which are code defects.
• Find the root cause of the repeated error in the sentinel table and stop if you cannot find it.
• Check whether the error we fixed last week has stopped recurring in production.

What are the safety notes for scripts and network use?

The skill listing states that it runs scripts and uses the network. The source does not list which scripts run or which endpoints are contacted, so review what runs before you install it in a sensitive environment. The source says error data stays in your own deployment under the sentinel discipline.

The workflow limits what it may change. It repairs on a branch or preview, never on production directly. Destructive changes, security-sensitive changes beyond an added check, and ambiguous fixes are deferred to a human. Every action is logged to an append-only record.

• Read SKILL.md and any files in the skill folder before use.
• Run it first against a preview or non-production deployment if you can.
• Pre-approve only the fix classes you are comfortable with, such as validator fixes, missing-index adds, ownership-check adds, and non-destructive backfills.
• Keep production merges and deploys under your own control.

What tips help the loop work well?

The loop depends on evidence. Make sure capture is working first, because a silent sentinel table gives the agent nothing to triage. Expect the agent to stop on hard-to-reproduce bugs. That is intended, since the source says a wrong fix is worse than an open error.

Use the pull request as the review point. The certification evidence is attached there, so reviewers can check the tsc result, rehearsal outcome, and reproduced-then-gone assertion without rerunning the work themselves.

• Confirm the sentinel skill captures errors before expecting fixes.
• Treat a stop-and-report outcome as a useful result, not a failure.
• Review the attached certification evidence before merging.
• Check the error signature after deploy, using the sentinel table and logs rather than insights.