skill-doctor
- Repo stars 3,406
- Author updated Live
- Author repo claude-octopus
- Domain
- Documentation
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @nyldn · no license declared
- Token usage
- Lean
- Setup complexity
- Manual integration
- External API key
- Required · Vendor-specific
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: skill-doctor
description: Environment diagnostics — check providers, auth, config, hooks, scheduler, and more Run environm…
category: documentation
runtime: Node.js
---
# skill-doctor output preview
## PART A: Task fit
- Use case: Environment diagnostics — check providers, auth, config, hooks, scheduler, and more Run environment diagnostics across 11 check categories. Identifies misconfigured providers, stale state, broken hooks, and other issues that prevent Claude Octopus from working correctly. requires Vendor-specific API key; runs on Node.js. Works with Claude Code, Cursor, Cl….
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Overview / When to Use / The Process” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Environment diagnostics — check providers, auth, config, hooks, scheduler, and more Run environment diagnostics across 11 check categories. Identifies misconfigured providers, stale state, broken hooks, and other issues that prevent Claude Octopus from working correctly. requires Vendor-specific API key; runs on Node.js. Works with Claude Code, Cursor, Cl…”.
- **02** When the source has headings, the agent prioritizes “Overview / When to Use / The Process” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands, read environment variables; may access external network resources; requires Vendor-specific API keys.
## Running Rules
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; requires Vendor-specific API keys.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/octo`, `/plugin`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands, read environment variables.
Start with a small task and check whether the result follows “Overview / When to Use / The Process”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-doctor
description: Environment diagnostics — check providers, auth, config, hooks, scheduler, and more Run environm…
category: documentation
source: nyldn/claude-octopus
---
# skill-doctor
## When to use
- Environment diagnostics — check providers, auth, config, hooks, scheduler, and more Run environment diagnostics across…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Overview / When to Use / The Process” and keep inference separate from source facts.
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; requires Vendor-specific API keys.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-doctor" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Overview / When to Use / The Process
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js | read files, write/modify files, run shell commands, read environment variables | may access external network resources
guardrails -> requires Vendor-specific API keys + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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, seeskills/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_PROFILEvalue (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.mdand.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 |
Decide Fit First
Design Intent
How To Use It
Boundaries And Review