/skill-doctor

name: skill-doctor
description: "Environment diagnostics — check providers, auth, config, hooks, scheduler, and more"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

Environment Doctor

Overview

Run environment diagnostics across 15 check categories. Doctor 2.0 identifies misconfigured providers, stale loaded or cached plugin versions, invalid plugin assembly, unwritable state, non-terminal run records, orphan process evidence, broken hooks, and other issues that prevent Claude Octopus from working correctly.

**Core principle:** Detect problems before they surface in workflows.

When to Use

**Use this skill when:**

• Something isn't working and you're not sure why
• After installing or updating the plugin
• Before a demo or important workflow run
• Checking if providers are properly authenticated
• Verifying scheduler, hooks, or skills are correctly configured

**Do NOT use for:**

• First-time setup (use `/octo:setup` — it guides configuration)
• Project workflow status (use `/octo:status`)
• Debugging application code (use `/octo:debug`)

The Process

Step 1: Resolve Plugin Root and Run Full Diagnostics

Use this resolver before running Octopus scripts. Prefer the active host root, then the stable root or the installed CLI. Do not create or replace a stable link while collecting diagnostics. Run this as a single Bash call.

OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-}}"
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then
  OCTO_BIN="$(command -v octopus)"
  OCTO_LINK_HOPS=0
  while [[ -L "$OCTO_BIN" ]]; do
    OCTO_LINK_HOPS=$((OCTO_LINK_HOPS + 1))
    if [[ "$OCTO_LINK_HOPS" -le 40 ]]; then
      OCTO_BIN_DIR="$(cd -P "$(dirname "$OCTO_BIN")" 2>/dev/null && pwd -P)" || { OCTO_BIN=""; break; }
      OCTO_LINK_TARGET="$(readlink "$OCTO_BIN")" || { OCTO_BIN=""; break; }
      case "$OCTO_LINK_TARGET" in
        /*) OCTO_BIN="$OCTO_LINK_TARGET" ;;
        *) OCTO_BIN="$OCTO_BIN_DIR/$OCTO_LINK_TARGET" ;;
      esac
    else
      OCTO_BIN=""
      break
    fi
  done
  if [[ -n "$OCTO_BIN" ]]; then
    OCTO_BIN_DIR="$(cd -P "$(dirname "$OCTO_BIN")" 2>/dev/null && pwd -P)" || OCTO_BIN_DIR=""
    [[ -z "$OCTO_BIN_DIR" ]] || OCTO_PLUGIN_ROOT="$(cd "$OCTO_BIN_DIR/.." 2>/dev/null && pwd -P)"
  fi
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="$(
    find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \
      | sed 's#/scripts/orchestrate.sh$##' \
      | { grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' || true; } \
      | sort \
      | tail -1
  )"
fi
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry doctor diagnostics."
  exit 1
fi
export OCTO_PLUGIN_ROOT
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

This runs all 15 check categories and displays a formatted report. The installation category reports a missing or mismatched stable root; it does not repair it.

Step 2: Filter by Category (Optional)

If the user asks about a specific area, reuse the resolver from Step 1 and replace its final `doctor --verbose` invocation with one of these lines. These are replacement lines, not standalone shell calls; `OCTO_PLUGIN_ROOT` must be resolved in the same Bash call.

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers --live
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor companions
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor config
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor updates
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor state
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor smoke
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor hooks
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor scheduler
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor skills
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor conflicts
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor agents
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor recurrence
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor cache
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor installation

Step 3: Check & Install Dependencies

Reuse the Step 1 resolver and replace its final invocation with the dependency checker to find missing CLIs, statusline config, and recommended plugins:

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" check

If the check reports missing deps, offer to install them:

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" install

This auto-installs Codex CLI, jq, and the statusline resolver. Antigravity CLI (`agy`) setup is detected and reported with install guidance. For plugins (claude-mem, document-skills), it prints `/plugin install` commands the user must run manually.

Step 4: Verbose or JSON Output

As above, run these as the final line of the Step 1 resolver call:

# Detailed output for troubleshooting
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json

# Combine: specific category +