self-healing — Claude Code skill for runtime recovery
self-healing — a skill for Claude Code and Codex helps an agent diagnose failures during a task and test its fix. It activates after a command, test, build, or lint run fails.
no license 109 installs ★ 341 updated 2026-10-19
npx skills add pskoett/pskoett-ai-skills --skill self-healing -a claude-codeWhat self-healing does
The skill guides an agent through finding the cause of a failure, applying a fix, rerunning the failed operation, and recording the result in .learnings/HEALS.md. Before adding an entry, the agent checks for a matching Pattern-Key so recurring problems update an existing record.
A fix counts as verified only after the operation runs again successfully. If the agent cannot test it, the entry is marked pending-verify; an unsuccessful fix is marked abandoned. The loop allows up to three attempts. Installing through Claude Code uses npx.
What it helps with
- trace why a command, test, build, or lint run failed
- repair a failure caused by a missing dependency or incorrect runtime
- create a helper script that the task needs
- record a tested fix so a recurring failure can be recognized
Example prompts for the agent
- Diagnose the
pytestfailure and rerun the test to check the fix. - Repair the build, then record the verified result in
.learnings/HEALS.md. - Look up the matching
Pattern-Keyand update its recurrence count.
How to install self-healing
1Skills CLI (Vercel)
npx skills add pskoett/pskoett-ai-skills --skill self-healing -a claude-code2Manually: put the files in place
~/.claude/skills/self-healing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/self-healing/
1Skills CLI (Vercel)
npx skills add pskoett/pskoett-ai-skills --skill self-healing -a codex2Manually: put the files in place
.agents/skills/self-healing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pskoett/pskoett-ai-skills --skill self-healing -a cursor2Manually: put the files in place
.cursor/skills/self-healing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pskoett/pskoett-ai-skills skills/self-healing2Manually: put the files in place
.github/skills/self-healing/SKILL.md1Skills CLI (Vercel)
npx skills add pskoett/pskoett-ai-skills --skill self-healing -a gemini-cli2Platform CLI
gemini skills install https://github.com/pskoett/pskoett-ai-skills --path skills/self-healingManually: put the files in place
.devin/skills/self-healing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pskoett/pskoett-ai-skills --skill self-healing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about self-healing
How do I install self-healing in Claude Code?
Run npx skills add pskoett/pskoett-ai-skills --skill self-healing -a claude-code. The skill file is located at ~/.claude/skills/self-healing/SKILL.md.
What does self-healing do?
It helps an agent diagnose a live failure, apply a fix, and rerun the failed operation. The agent then records the result and verification evidence in .learnings/HEALS.md.
How does self-healing handle recurring failures?
Before creating a record, the agent searches HEALS.md for a matching Pattern-Key. A recurrence updates Recurrence-Count instead of creating a duplicate entry.