skill-doctor

name	skill-doctor
version	1.0
category	openclaw-native
description	Diagnoses silent skill discovery failures — YAML parse errors, path violations, schema mismatches — so broken skills don't disappear without a trace.
stateful	true

Skill Doctor

What it does

OpenClaw loads skills at startup. When a skill fails to load — corrupt frontmatter, bad cron expression, mismatched STATE_SCHEMA — it silently disappears from the registry. There is no error surfaced to the agent.

Skill Doctor runs a full diagnostic pass over all installed skills and reports every failure that would cause silent non-loading, so you can fix problems before they become invisible gaps.

When to invoke

• After installing new skills or upgrading openclaw-superpowers
• When a skill you expect to find is missing from the registry
• As a post-install gate inside install.sh
• Manually, any time something feels off with skill behaviour

Diagnostic checks

Skill Doctor runs 6 checks per skill:

Check	Failure condition
YAML parse	Frontmatter cannot be parsed by a YAML parser
Required fields	name or description absent from frontmatter
Path conventions	Skill directory name does not match name: field
Cron format	cron: present but not a valid 5-field cron expression
Stateful coherence	stateful: true but STATE_SCHEMA.yaml missing
Schema validity	STATE_SCHEMA.yaml present but missing version: or fields:

Output levels

• PASS — skill will load correctly
• WARN — skill loads but has a non-critical issue (e.g. schema present but stateful: missing)
• FAIL — skill will not load; must fix before use

How to use

python3 doctor.py --scan                   # Full diagnostic pass
python3 doctor.py --scan --only-failures   # Show FAILs only
python3 doctor.py --scan --skill cron-hygiene   # Single skill
python3 doctor.py --fix-hint cron-hygiene  # Print actionable fix suggestion
python3 doctor.py --status                 # Summary of last scan
python3 doctor.py --format json            # Machine-readable output

Procedure

Step 1 — Run the scan

python3 doctor.py --scan

Review the output. Each skill gets a one-line verdict: PASS / WARN / FAIL.

Step 2 — Triage FAILs first

For each FAIL, run --fix-hint <skill-name> to get an actionable repair suggestion. Skill Doctor never modifies skill files itself — it tells you exactly what to change.

Step 3 — Review WARNs

WARNs do not block loading but indicate drift from conventions. Common WARN: STATE_SCHEMA.yaml exists without stateful: true in frontmatter. Fix by adding the frontmatter field.

Step 4 — Re-scan to confirm

After applying fixes, re-run --scan and verify no FAILs remain.

Step 5 — Write scan result to state

After a clean pass, the scan summary is automatically written to state. Use --status in future sessions to surface the last known health without re-scanning.

State

Skill Doctor persists scan results in ~/.openclaw/skill-state/skill-doctor/state.yaml.

Fields: last_scan_at, skills_scanned, fail_count, warn_count, violations list.

After a clean install, fail_count and warn_count should both be 0.

Integration

Add to the end of install.sh:

echo "Running Skill Doctor post-install check..."
python3 ~/.openclaw/extensions/superpowers/skills/openclaw-native/skill-doctor/doctor.py --scan --only-failures

This surfaces any broken skills immediately after install rather than letting them silently disappear.