CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

self-healing

Active runtime recovery for coding agents: when something breaks mid-task, diagnose the root cause, write a fix, VERIFY by re-running the broken thing, then file a `HEAL-` entry to `.learnings/HEALS.md` with proof. Use whenever a command, test, build, or lint fails or exits non-zero; on missing tooling, dependency/lockfile mismatch, wrong runtime version, venv or permission errors, port conflicts, dirty git state, or a missing `.env`; when the agent needs a helper or one-off script that doesn't exist yet; when an external API, tool, or MCP errors or rate-limits; or when a test flakes. Search `HEALS.md` by `Pattern-Key` first — most heals are recurrences, so increment `Recurrence-Count` instead of duplicating. Verify is mandatory: mark `pending-verify` honestly if sandboxed, `abandoned` if the fix can't be made to work. Pairs with `self-improvement` (which promotes recurring heals to durable memory) but owns the verify-before-persist discipline self-improvement doesn't.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is self-healing in pskoett/pskoett-ai-skills

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A strong, highly actionable process skill: the heal loop is clearly sequenced with mandatory verification, explicit proof criteria, retry caps, and honest abandoned/pending-verify states. Its weaknesses are token redundancy — the verify-before-persist mantra and recurrence guidance are repeated across multiple sections — and the failure to surface the three bundled helper scripts that automate exactly what the body teaches manually.

Suggestions

State the verify-before-persist rule once authoritatively (e.g., in Verification rules) and cross-reference it from the loop, anti-patterns, and best practices instead of restating it five times; trim the motivational 'What this skill is for' failure-modes intro and the hedging in the skill-review boundary section.

Surface the bundled scripts in SKILL.md: reference scripts/new-heal.sh for entry scaffolding, scripts/find-similar-heals.sh for the recurrence search, and scripts/detect-failure.sh alongside references/hooks.md for hook-based triggering — the body currently teaches manual equivalents while executable helpers go undocumented.

Move the ~20-line 'When a skill contributed to the failure' approval-boundary section into a reference file, keeping a two-line boundary rule inline, to cut repetition and reduce main-skill token cost.

DimensionReasoningScore

Conciseness

The body is dense operational rules with no basic-concept padding, but the core 'verify before persist' discipline is restated roughly five times (loop diagram, 'What this skill is for', verification rules, anti-patterns, best practices), and the motivational failure-modes intro plus the hedging-heavy 'When a skill contributed to the failure' section could be trimmed. This matches anchor 3 (mostly efficient but includes some unnecessary explanation or could be tightened) better than anchor 4 — the repetition goes beyond minor over-explanation.

3 / 5

Actionability

Provides a copy-paste-ready HEAL entry template, an exact grep command for recurrence detection, setup commands, ID format with examples, and a proof-criteria table per failure shape. Fully executable guidance covering the common cases, matching anchor 5; there are no execution gaps in the core workflow.

5 / 5

Workflow Clarity

The Heal Loop diagram sequences DIAGNOSE→PATCH→VERIFY→FILE with a 3-attempt retry cap, an explicit escalation ladder on verification failure (once/twice/three times), an abandonment path, and failure classification (deterministic/transient/shared-service) required before any retry. This is the exact validate→fix→retry feedback-loop pattern with explicit checkpoints that anchor 5 describes.

5 / 5

Progressive Disclosure

All four references (examples.md, hooks.md, interop-with-self-improvement.md, pipeline-integration.md) exist, are clearly signaled with one-line purpose annotations, and are one level deep. However, the three bundled scripts (new-heal.sh, find-similar-heals.sh, detect-failure.sh) are never mentioned in the body — it teaches manual grep and manual entry writing while executable helpers sit undocumented. Good structure with a real but contained organization gap, matching anchor 4 rather than the fully-split anchor 5.

4 / 5

Total

17

/

20

Passed

Description

96%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An excellent description: it explicitly states what the skill does and when to use it with a comprehensive, natural set of concrete trigger phrases, and it proactively disambiguates from the adjacent self-improvement skill. The only residual risk is mild trigger overlap with that sibling skill, which the description itself acknowledges and bounds.

DimensionReasoningScore

Specificity

Lists multiple concrete actions covering the entire loop — 'diagnose the root cause, write a fix, VERIFY by re-running the broken thing, then file a HEAL- entry to .learnings/HEALS.md with proof' — plus recurrence handling ('increment Recurrence-Count instead of duplicating') and honest status marking ('pending-verify', 'abandoned'). Comprehensive coverage with no gaps, matching anchor 5 rather than anchor 4.

5 / 5

Completeness

Explicitly answers both questions: the what ('Active runtime recovery... diagnose, write a fix, VERIFY by re-running the broken thing, then file a HEAL- entry with proof') and the when ('Use whenever a command, test, build, or lint fails or exits non-zero; on missing tooling...'). Both are concrete and fully explicit, matching anchor 5 rather than anchor 4's 'when could be more specific'.

5 / 5

Trigger Term Quality

Covers the natural trigger phrases an agent or user would actually encounter: 'command, test, build, or lint fails or exits non-zero', 'dependency/lockfile mismatch', 'venv or permission errors', 'port conflicts', 'dirty git state', 'missing .env', 'errors or rate-limits', 'test flakes', plus the helper-gap case. Includes synonyms and concrete file names, matching anchor 5's comprehensive coverage rather than anchor 4's 'a few natural terms missing'.

5 / 5

Distinctiveness Conflict Risk

The description explicitly draws the boundary with its closest sibling — 'Pairs with self-improvement... but owns the verify-before-persist discipline self-improvement doesn't' — and its failure-shaped triggers (non-zero exits, missing .env, port conflicts) are distinct from self-improvement's reflective triggers. Still, 'when a test flakes' and recurrence handling sit near self-improvement's territory, leaving minor overlap risk with a closely related skill, which is exactly anchor 4 rather than anchor 5's minimal-conflict niche.

4 / 5

Total

19

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 2 missing

Warning

Total

15

/

16

Passed

Repository

pskoett/pskoett-ai-skills

Path

agent-plugin/skills/self-healing/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.