Skill Doctor | OpenClaw Skill

Scans workspace/skills (or a given folder) to detect missing and unused Python dependencies, can fix requirements.txt (add missing, optionally remove unused), and can test a skill using the skill-tester in sandbox (default) or no-sandbox mode.

Description

Scan: For each skill, finds all Python files under the skill and its scripts/ folder, extracts top-level imports, and compares them to requirements.txt. Reports:
Missing: Imported but not listed in requirements (suggests adding).
Unused: Listed in requirements but not imported (suggests removing).
Fix: Adds missing packages to requirements.txt and/or removes unused ones (--fix-unused).
Test: Runs the skill-tester for the given skill. Use --no-sandbox to run tests with full environment (e.g. network); default runs in sandbox.

Stdlib modules and local modules (same skill’s .py files) are excluded from “missing”.

Installation

clawhub install skill-doctor

Or clone into your skills directory:

git clone https://github.com/Org/skill-doctor.git workspace/skills/skill-doctor

Usage

# Scan all skills (or default: scan)
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py

# Scan one skill
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill SUBAGENT-DASHBOARD --scan

# Fix: add missing deps to requirements.txt
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill MY-SKILL --fix

# Fix: add missing and remove unused
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill MY-SKILL --fix --fix-unused

# Dry-run fix (report only)
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill MY-SKILL --fix --fix-unused --dry-run

# Test skill (sandbox)
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill gateway-guard --test

# Test skill (no sandbox: full env)
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill gateway-guard --test --no-sandbox

# JSON output
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --scan --json
python3 workspace/skills/skill-doctor/scripts/skill_doctor.py --skill X --test --json

Commands

Command / flags	Description
`--scan`	Scan skills and report missing/unused dependencies (default if no `--fix`/`--test`)
`--skill SLUG`	Limit to one skill
`--fix`	Add missing packages to `requirements.txt`
`--fix-unused`	With `--fix`, also remove unused packages
`--dry-run`	With `--fix`: only report what would be done
`--test`	Run skill-tester for the skill
`--no-sandbox`	Run tests with full env (no sandbox)
`--timeout N`	Test timeout in seconds (default 60)
`--json`	Output JSON
`--skills-dir PATH`	Override skills root (default: `workspace/skills`)

What this skill does

Discover skills — Finds dirs with SKILL.md or _meta.json under the skills folder.
Parse Python — Uses ast to collect top-level import / import from names from all .py files in the skill and scripts/.
Exclude stdlib and local — Ignores standard library modules and local modules (same skill’s file names).
Map to pip — Maps import names to pip package names (e.g. bs4 → beautifulsoup4, yaml → PyYAML).
Compare — Compares required (from requirements.txt) vs needed (from imports); reports missing and unused.
Fix — Writes requirements.txt: append missing packages; optionally remove unused lines.
Test — Invokes skill-tester/scripts/skill_tester.py --skill SLUG --json. Sandbox vs no-sandbox is controlled by --no-sandbox and the OPENCLAW_DOCTOR_NO_SANDBOX env var for the test run.

Requirements

Python 3.7+
Optional: skill-tester for --test (must be present under workspace/skills/skill-tester).

Security & privacy

Reads: Skill directories and their .py and requirements.txt files.
Writes: Only requirements.txt when using --fix (and --fix-unused).
Test: Runs skill-tester in a subprocess; --no-sandbox means tests run with the current environment (e.g. network allowed).