skill-doctor

Documentation Community

Repo stars 3,406
Author repo claude-octopus

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Environment diagnostics — check providers, auth, config, hooks, scheduler, and more Run environment diagnostics across 11 check…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Overview”, “When to Use”, “The Process”, “Step 1: Resolve Plugin Root and Run Full Diagnostics”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-doctor directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Overview / When to Use / The Process” before expanding.

Boundaries And Review

Dependencies: Prepare Vendor-specific API keys before running a full task.
Permissions: Declared permissions include read / write / shell-exec / env-read; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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 /octo:doctor."
  exit 1
fi
mkdir -p "${HOME}/.claude-octopus"
ln -sfn "$OCTO_PLUGIN_ROOT" "${HOME}/.claude-octopus/plugin" 2>/dev/null || true
export OCTO_PLUGIN_ROOT
cd "$OCTO_PLUGIN_ROOT" && bash 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:

cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor providers
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor auth
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor config
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor state
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor smoke
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor hooks
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor scheduler
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor skills
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor conflicts
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor agents
cd "${HOME}/.claude-octopus/plugin" && bash 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. 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
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --verbose

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

# Combine: specific category + verbose
cd "${HOME}/.claude-octopus/plugin" && bash 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 providers (Codex/Gemini not installed):

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: "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

Category	What it checks
`providers`	Claude Code version, Codex CLI installed, Gemini CLI installed, Perplexity API key, Ollama local LLM (server + models), circuit breaker status, provider fallback history
`auth`	Authentication status for each provider
`config`	Plugin version, install scope, feature flags
`state`	Project state.json, stale results, workspace writable
`smoke`	Smoke test cache, model configuration
`hooks`	hooks.json validity, hook scripts
`scheduler`	Scheduler daemon, jobs, budget gates, kill switches
`skills`	Skill files loaded and valid
`conflicts`	Conflicting plugins detection
`agents`	Agent definitions, worktree isolation, CLI registration, version compatibility
`recurrence`	Failure pattern detection — flags repeated quality gate failures, source hotspots, 48h trends
`deps`	Software dependencies — Node.js, jq, Codex/Gemini CLIs, RTK token compression (gain stats + hook status), statusline resolver, recommended plugins

Interpreting Results

Healthy Output

All checks pass — no action needed.

Common Issues and Fixes

Issue	Fix
Codex CLI not found	`npm install -g @openai/codex` or install via `codex login`
Gemini CLI not found	Install Gemini CLI from Google
Perplexity not configured	`export PERPLEXITY_API_KEY="pplx-..."` (optional)
Auth expired	Re-run `codex login` or `gemini login`
Circuit breaker OPEN	Provider had 3+ consecutive transient failures — wait for cooldown or check provider status
Stale state	Delete `.octo/state.json` and re-initialize
Invalid hooks.json	Check `hooks.json` syntax — must be valid JSON
RTK not installed	Offer to install: `brew install rtk && rtk init -g` (saves 60-90% tokens). Use AskUserQuestion to offer brew vs cargo install.
RTK installed but hook not configured	On macOS/Linux, offer `rtk init -g`; on Windows Git Bash, report skipped because RTK uses CLAUDE.md injection mode
RTK gain stats unavailable	Run some bash commands first, then check `rtk gain` to see token savings
Conflicting plugins	Uninstall conflicting plugins or adjust scope

Integration with Other Skills

Scenario	Route
Doctor finds missing provider	Suggest `/octo:setup` to configure
Doctor finds stale project state	Suggest `/octo:status` to review
Doctor finds hook errors	Guide user to fix hooks.json
All checks pass, user still has issues	Suggest `/octo:debug` for deeper investigation

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

Dimension	budget	balanced	quality
Hooks	essential only	standard (no quality gates)	all hooks
Models	Sonnet everywhere	Sonnet + Opus for synthesis	Opus for most phases
Phases	Skip discover if context given	Skip re-discovery	All phases run
Context	Compressed	Standard	Full inlining

Project Tier Hint

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

Tier	Doctor guidance
`prototype`	Prefer faster checks and warn before high-cost provider fanout
`mvp`	Use balanced defaults and consensus on risky changes
`production`	Recommend full verification, security review, and stricter release gates

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

User Input	Action
`/octo:doctor`	Run all 11 categories
`/octo:doctor providers`	Check provider installation only
`/octo:doctor auth --verbose`	Detailed auth status
`/octo:doctor --json`	Machine-readable output

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Documentation
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @nyldn · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Manual integration
External API key: Required · Vendor-specific
Detected OS requirements: macOS · Linux · Windows
Runtime requirements: Node.js
Detected file/system behavior: Read-only
Write / modify
Shell exec
Env read
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-doctor.preview

# Step 4: Verbose or JSON Output

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

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

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

SKILL.md SKILL.md

> **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.

```bash
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)"

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Overview → When to Use → The Process → Step 1: Resolve Plugin Root and Run Full Diagnostics → Step 2: Filter by Category (Optional) → Step 3: Check & Install Dependencies
terms    -> Host: Codex CLI · Core principle · Use this skill when · Do NOT use for · RTK not installed · RTK installed but hook not configured on macOS/Linux · Missing providers (Codex/Gemini not installed) · Auth expired
files/cmd -> /octo: · skills/blocks/codex-host-adapter.md · /octo:setup · /octo:status · /octo:debug · ~/.claude-octopus/plugin · /plugin install · rtk init -g
body sha256 -> 65576afc7b3d

Decide Fit First

Design Intent

How To Use It

Boundaries And Review

Environment Doctor

Overview

When to Use

The Process

Step 1: Resolve Plugin Root and Run Full Diagnostics

Step 2: Filter by Category (Optional)

Step 3: Check & Install Dependencies

Step 4: Verbose or JSON Output

Step 5: Interactive Remediation (MANDATORY for fixable issues)

Check Categories

Interpreting Results

Healthy Output

Common Issues and Fixes

Integration with Other Skills

Hook Profile

Intensity Profile

What the Doctor Checks

Profile Summary

Project Tier Hint

Remote Session Checks

Runtime Context

What the Doctor Checks

Why It Matters

Quick Reference

Discussion