Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/skill-doctor
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Environment diagnostics — check providers, auth, config, hooks, scheduler, and more
📊 Stats
Stars3,869
Forks362
LanguageShell
LicenseMIT
📦 Ships with octo
</> SKILL.md
skill-doctor.SKILL.md
---name: skill-doctor
effort: low
description: "Environment diagnostics — check providers, auth, config, hooks, scheduler, and more"
trigger: |
AUTOMATICALLY ACTIVATE when user asks about:
- "doctor" or "run doctor" or "diagnostics"
- "check my setup" or "is everything working"
- "health check" or "environment check"
- "what's wrong with my setup" or "why isn't octopus working"
- "check providers" or "check auth" or "check hooks"
DO NOT activate for:
- Initial setup (use /octo:setup)
- Project status or workflow progress (use /octo:status)
- Debugging application code (use /octo:debug)
---# 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
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
```bash
# 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:**
```javascript
AskUserQuestion({
questions: [{
question: "RTK saves 60-90% on bash output tokens. Install it now?",
| 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 |
| 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 |
