Openclaw-superpowers skill-doctor

Diagnoses silent skill discovery failures — YAML parse errors, path violations, schema mismatches — so broken skills don't disappear without a trace.

install

source · Clone the upstream repo

git clone https://github.com/ArchieIndian/openclaw-superpowers

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ArchieIndian/openclaw-superpowers "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/openclaw-native/skill-doctor" ~/.claude/skills/archieindian-openclaw-superpowers-skill-doctor && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ArchieIndian/openclaw-superpowers "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/openclaw-native/skill-doctor" ~/.openclaw/skills/archieindian-openclaw-superpowers-skill-doctor && rm -rf "$T"

manifest: skills/openclaw-native/skill-doctor/SKILL.md

source content

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.