Skill Doctor

intent

skill-doctor audits python dependencies across your skill codebase by scanning imports against requirements.txt, detecting gaps and cruft. use it to keep dependency manifests accurate, optionally auto-fix them, and validate skills with skill-tester in sandbox or unrestricted modes. run this regularly or before deploying skills to catch stale packages and import errors early.

inputs

• skills directory path: defaults to workspace/skills; override with --skills-dir PATH. must contain skill folders with SKILL.md or _meta.json markers.
• skill slug: optional --skill SLUG to audit a single skill instead of all.
• skill-tester: required only for --test mode. must exist at workspace/skills/skill-tester. expects scripts/skill_tester.py executable.
• environment variables (optional):
  • OPENCLAW_DOCTOR_NO_SANDBOX: set to true to default all test runs to no-sandbox mode; cli --no-sandbox overrides.
  • OPENCLAW_DOCTOR_TIMEOUT: default test timeout in seconds (default 60 if not set); cli --timeout N overrides.

procedure

1. discover skills (inputs: skills directory path). scan the skills root for subdirectories containing SKILL.md or _meta.json. build list of skill slugs (directory names). output: list of skill paths.

2. parse imports per skill (inputs: skill path, scripts/ subdirectory). for each skill, walk all .py files in the skill root and scripts/ folder. use ast.parse() to extract top-level import X and from X import Y statements. collect unique module names (the leftmost part of dotted names, e.g. from foo.bar import baz captures foo). output: set of import names per skill.

3. exclude stdlib and local modules (inputs: import names, skill directory). filter out python standard library names (check against sys.stdlib_list or curated list). filter out local modules matching .py filenames in the same skill directory (e.g. if utils.py exists, exclude utils from the import set). output: external dependency names only.

4. map import names to pip packages (inputs: external dependency names). apply known mappings for packages where import name differs from pip name (e.g. bs4 → beautifulsoup4, yaml → PyYAML, cv2 → opencv-python, PIL → Pillow). for unmapped names, assume import name equals pip name. output: canonical pip package names.

5. read requirements.txt (inputs: skill path). load requirements.txt from skill root (if missing, treat as empty). parse lines, extract package names (ignoring versions, extras, comments, blank lines). output: set of required packages.

6. compare and report (inputs: required packages, canonical pip packages). compute missing (in imports but not in requirements.txt) and unused (in requirements.txt but not in imports). if --json flag set, emit json report; else emit human-readable table. output: report data structure with missing and unused lists.

7. fix requirements.txt (conditional) (inputs: report data, skill path, --fix flag). if --fix flag present, append missing packages to requirements.txt (one per line, no version pinning unless original file has pinned versions; if so, append with == and current pip version or >= if version unknown). if --fix-unused flag also present, remove unused package lines. if --dry-run flag set, do not write; only print what would be changed. output: updated requirements.txt or dry-run report.

8. test skill (conditional) (inputs: skill slug, --test flag, sandbox/no-sandbox mode, timeout). if --test flag present, invoke skill-tester subprocess: python3 workspace/skills/skill-tester/scripts/skill_tester.py --skill SLUG --json --timeout N. capture stdout/stderr and exit code. if --no-sandbox flag set or OPENCLAW_DOCTOR_NO_SANDBOX=true, pass --no-sandbox to skill-tester. if test subprocess times out (exceeds --timeout or env default), terminate and report timeout error. if --json flag set, pass through skill-tester's json output; else emit human-readable test result. output: test result (pass/fail, test logs, coverage if available).

decision points

• if --fix flag absent: skip step 7; only report missing/unused.
• if --fix-unused flag absent: in step 7, add missing packages but do not remove unused lines.
• if --dry-run flag set: in step 7, print the changes but do not modify requirements.txt.
• if --test flag absent: skip step 8; do not invoke skill-tester.
• if --no-sandbox flag set or OPENCLAW_DOCTOR_NO_SANDBOX=true: pass --no-sandbox to skill-tester in step 8; else run in default sandbox mode.
• if requirements.txt does not exist: in step 5, treat as empty file; in step 7 (with --fix), create a new requirements.txt with missing packages.
• if skill-tester not found at workspace/skills/skill-tester: in step 8, emit error and fail the test; do not proceed.
• if --skill flag absent: in step 1, discover and process all skills; else process only the specified skill slug.
• if import name maps to multiple pip packages (e.g. cv2 could be opencv-python or opencv-python-headless): use the most common mapping; document in error if ambiguous.
• if skill-tester subprocess times out: terminate subprocess, emit timeout error, return non-zero exit code.
• if --json flag set: emit all output (report, test results) as json objects on separate lines (jsonl format); else emit human-readable tables and text.

output contract

scan mode (default or --scan):

• human output: table with columns: skill slug, missing packages (comma-separated or count), unused packages (comma-separated or count). summary line with total counts.
• json output: array of objects: {skill: "slug", missing: ["pkg1", "pkg2"], unused: ["pkg3"]}

fix mode (--fix, with or without --fix-unused):

• human output: print per-skill: "added X packages to requirements.txt: [list]", "removed Y packages: [list]", or "(dry-run: would add/remove)".
• json output: object per skill: {skill: "slug", action: "fix", added: ["pkg"], removed: [], dry_run: false}
• file output (if not dry-run): update <skill>/requirements.txt with missing packages appended and/or unused packages removed.

test mode (--test):

• human output: per-skill test result: "PASS" or "FAIL", followed by brief test summary (e.g. "5 tests passed, 1 failed") or error message.
• json output: object per skill: {skill: "slug", action: "test", result: "pass" or "fail", tests_passed: N, tests_failed: N, error: null or string, sandbox: true or false}
• no file output from skill-doctor itself (skill-tester may create logs or artifacts in its own directory).

error cases:

• missing skill-tester: {error: "skill-tester not found at workspace/skills/skill-tester"}
• invalid skill slug: {error: "skill 'UNKNOWN' not found"}
• requirements.txt parse error: {error: "failed to parse requirements.txt: <details>"}
• test timeout: {error: "test timeout after N seconds", skill: "slug"}
• network/io error: {error: "permission denied reading skill directory", detail: <system error>}

outcome signal

• scan succeeded: console shows dependency audit table with no errors. json output is valid and complete.
• fix succeeded: requirements.txt is updated (or dry-run confirms what would change). no write errors reported.
• test succeeded: console shows "PASS" or individual test status. exit code is 0. json output includes result: "pass".
• failure: any step emits error (missing skill, parse failure, timeout, permission denied, invalid flag). exit code is non-zero. error message is clear and actionable.