/installation-doctor

name: installation-doctor
description: >-
  Diagnose cc-thingz plugin installations with the bundled read-only doctor.
  Use for missing installed skills, helpers, or hook files, stale package
  versions, duplicate packages, or migration from old cc-thingz packages. NOT for broad agent
  configuration audits or config edits; use evolving-config.

Installation Doctor

Inspect installed resources without a repository checkout. The helper compares files against its bundled release catalog; it does not execute hooks or modify installations.

Run

1. Locate `scripts/doctor.py` relative to this installed `SKILL.md`. 2. Use an existing Python 3.12+ interpreter with `-B`. If using uv, run `uv run --no-project python -B <skill-directory>/scripts/doctor.py --json`. uv may populate its own cache; use an existing interpreter directly when the entire invocation must be read-only. 3. Select roots for the requested runtime. Without root options the helper inspects the Codex cc-thingz marketplace cache and user flat skill directories. For Claude or a specific installation, pass `--plugin-root <directory>`. Repeat `--plugin-root` or `--skill-root` for multiple locations. Any explicit root option restricts inspection to supplied roots. 4. Optionally pass `--config-root <.codex-directory>` to check agent profile presence, or `--repo <cc-thingz-checkout>` for comparison with source manifests. 5. Summarize failed checks with paths, migration suggestions, and verification gaps. Exit 1 means findings; exit 2 means invalid arguments.

Interpretation

• Cached copies do not prove enabled plugins or duplicate execution. Inspect the

runtime's enabled-plugin list before recommending removal.

• Versions are compared with the release containing this helper, not an online

latest release. Without a containing native manifest, version checks are skipped.

• `hook-files` fails when a hook registration names a plugin file that is not

on disk. A running session keeps the plugin root it started with; after a plugin update replaces that versioned directory, its hooks exit 127 or deny with "can't open file" even though the new install passes. Restart those sessions.

• Hook support, helper dependencies, active plugins, and effective permissions

remain unsupported by static inventory; exit 0 does not verify them.

• Report missing Python or unreadable metadata precisely. Do not install tools,

change configuration, or delete caches as part of this diagnostic run.

Output

Report the inspected roots, baseline release, confirmed findings with paths, skipped or unsupported checks, and the next corrective action. Keep hook commands and credential contents out of the response.