skill-doctor

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

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 11 check categories. Identifies misconfigured providers, stale state, 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. Do not assume ~/.claude-octopus/plugin exists; Windows Git Bash installs may not support the stable symlink. Run this as a single Bash call.

OCTO_PLUGIN_ROOT="${CLAUDE_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_PLUGIN_ROOT="$(cd "$(dirname "$OCTO_BIN")/.." && pwd)"
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]|$))' \
      | 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
mkdir -p "${HOME}/.claude-octopus"
_octo_stable="${HOME}/.claude-octopus/plugin"
if [[ ! -L "$_octo_stable" ]] || [[ "$(cd "$OCTO_PLUGIN_ROOT" 2>/dev/null && pwd -P)" != "$(cd "$_octo_stable" 2>/dev/null && pwd -P)" ]]; then
  [[ -L "$_octo_stable" || -f "$_octo_stable" ]] && rm -f "$_octo_stable" 2>/dev/null || true
  ln -s "$OCTO_PLUGIN_ROOT" "$_octo_stable" 2>/dev/null || true
fi
unset _octo_stable
export OCTO_PLUGIN_ROOT
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor

This runs all 11 check categories and displays a formatted report.

Step 2: Filter by Category (Optional)

If the user asks about a specific area, filter:

bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor providers
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor auth
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor config
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor state
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor smoke
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor hooks
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor scheduler
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor skills
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor conflicts
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor agents
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor recurrence

Step 3: Check & Install Dependencies

Run the dependency checker to find missing CLIs, statusline config, and recommended plugins:

bash "${HOME}/.claude-octopus/plugin/scripts/install-deps.sh" check

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

bash "${HOME}/.claude-octopus/plugin/scripts/install-deps.sh" install

This auto-installs: Codex CLI, Gemini 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

# Detailed output for troubleshooting
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor --json

# Combine: specific category + verbose
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor auth --verbose

Step 5: Interactive Remediation (MANDATORY for fixable issues)

After running diagnostics, if ANY fixable issues are found, you MUST use AskUserQuestion to offer fixes. Do NOT just print instructions — offer to execute them.

RTK not installed:

AskUserQuestion({
  questions: [{
    question: "RTK saves 60-90% on bash output tokens. Install it now?",
    header: "Install RTK",
    multiSelect: false,
    options: [
      {label: "Install via brew (Recommended)", description: "brew install rtk — fast, macOS"},
      {label: "Install via cargo", description: "cargo install rtk-token-killer"},
      {label: "Skip", description: "Continue without RTK"}
    ]
  }]
})

If user chooses install, run it, then offer hook setup.

RTK installed but hook not configured on macOS/Linux:

On Windows Git Bash, do not offer rtk init -g. RTK uses CLAUDE.md injection mode there, so report the hook check as skipped.

AskUserQuestion({
  questions: [{
    question: "RTK is installed but the Claude Code hook isn't active. Configure it?",
    header: "RTK Hook",
    multiSelect: false,
    options: [
      {label: "Run rtk init -g (Recommended)", description: "Auto-installs Claude Code bash hook on macOS/Linux"},
      {label: "Skip", description: "I'll configure it later"}
    ]
  }]
})

Missing optional providers:

AskUserQuestion({
  questions: [{
    question: "Some providers are missing. Install them?",
    header: "Providers",
    multiSelect: true,
    options: [
      {label: "Codex CLI", description: "npm install -g @openai/codex"},
      {label: "Gemini CLI", description: "brew install gemini-cli (macOS)"},
      {label: "Antigravity CLI", description: "Install agy, then verify with agy --version && agy models"},
      {label: "Skip all", description: "Continue with available providers"}
    ]
  }]
})

Auth expired: Offer to run the login command for the expired provider.

Multiple fixable issues: Batch them into a single AskUserQuestion with multiSelect where appropriate, rather than asking one at a time.

Check Categories

Interpreting Results

Healthy Output

All checks pass — no action needed.

Common Issues and Fixes

Integration with Other Skills

Hook Profile

Claude Octopus hooks can run in different profiles to balance cost and coverage.

Current profile: $OCTO_HOOK_PROFILE (default: standard)

Available profiles:

• minimal — Only session lifecycle and cost tracking hooks (lowest overhead)
• standard — All hooks except expensive review/security gates (default)
• strict — All hooks enabled including quality and security gates

Override: Set OCTO_PROFILE=budget|balanced|quality or OCTO_DISABLED_HOOKS=hook1,hook2 to fine-tune. Legacy OCTO_HOOK_PROFILE still works (minimal→budget, standard→balanced, strict→quality).

Intensity Profile

The doctor reports the active intensity profile — a single knob controlling hook gating, model selection, phase skipping, and context verbosity.

What the Doctor Checks

• Current profile: OCTO_PROFILE value (budget/balanced/quality, default: balanced)
• Profile source: env var, legacy OCTO_HOOK_PROFILE, or auto-selected from intent
• Hook gating: which hooks are enabled/disabled at this profile level
• Model hints: which model (sonnet/opus) is recommended for each phase
• Context verbosity: compressed/standard/full

Profile Summary

Project Tier Hint

Also report OCTO_TIER when set. This is a recommendation hint, not a hard policy.

If unset, show OCTO_TIER=unset and suggest setting it only when the project has a stable risk profile.

Remote Session Checks

If CLAUDE_CODE_REMOTE=true or OCTOPUS_REMOTE_SESSION=true, report:

• remote session detected
• autonomous mode default active when no explicit autonomy is set
• provider probes skipped to conserve time/quota
• full HUD disabled unless OCTOPUS_REMOTE_STATUSLINE=full
• provider CLIs may need to be installed in the cloud setup script

Suggest /octo:setup only for configuration guidance; do not recommend interactive provider logins inside the remote session.

Runtime Context

The doctor checks for project-level RUNTIME.md — a file that provides project-specific context (API endpoints, env vars, test commands, build steps) to orchestration prompts.

What the Doctor Checks

• RUNTIME.md exists in the project root (also checks .octopus/RUNTIME.md and .claude-octopus/RUNTIME.md)
• If missing, suggest creating one from the template: cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.md
• If present, confirm it contains at least one populated section (not just the template defaults)

Why It Matters

Without a RUNTIME.md, orchestration prompts lack project-specific details — leading to generic advice about test commands, environment variables, and build steps. A populated RUNTIME.md makes every workflow more accurate.

Quick Reference

/octo:doctor was removed in v9.41.0 to preserve Claude Code's native /doctor command. Invoke this skill by asking Claude naturally, or run the orchestrator directly: