skill-doctor

name	skill-doctor
displayName	Skill Doctor | OpenClaw Skill
description	Scans the skills folder for new, unused, or missing dependencies; fixes requirements.txt; and tests a skill in or out of sandbox.
version	1.0.0

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

1. Discover skills — Finds dirs with SKILL.md or _meta.json under the skills folder.
2. Parse Python — Uses ast to collect top-level import / import from names from all .py files in the skill and scripts/.
3. Exclude stdlib and local — Ignores standard library modules and local modules (same skill’s file names).
4. Map to pip — Maps import names to pip package names (e.g. bs4 → beautifulsoup4, yaml → PyYAML).
5. Compare — Compares required (from requirements.txt) vs needed (from imports); reports missing and unused.
6. Fix — Writes requirements.txt: append missing packages; optionally remove unused lines.
7. 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).