/doctor

description: "OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks."
argument-hint: "[--verbose]"
disable-model-invocation: false
model: haiku
effort: low
context: inherit
user-invocable: true
name: doctor
allowed-tools: [Bash, Read, Grep, Glob, AskUserQuestion]

Auto-generated from skills/doctor/SKILL.md

Source: https://github.com/yonatangross/orchestkit

OrchestKit Health Diagnostics

Argument Resolution

FLAGS = "$ARGUMENTS"         # Full argument string, e.g., "--verbose" or "--json"
FLAG = "$ARGUMENTS[0]"       # First token: -v, --verbose, --json, --category=X
# $ARGUMENTS[0], $ARGUMENTS[1] for indexed access (CC 2.1.59)

STEP 0: Choose Scope (AskUserQuestion — M118 #1464)

A full doctor run takes ~20s. Most invocations only need one slice. Ask the user up-front so voice-flow shortcuts ("just the MCPs") map cleanly:

# Skip the prompt when an explicit scope arg or env override is present:
#   /ork:doctor cc      → skip, use cc-only
#   /ork:doctor mcp     → skip, use mcp-only
#   /ork:doctor plugin  → skip, use plugin-only
#   ORK_DOCTOR_SCOPE=all (or any of the above) → skip, use the env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
  "question": "What should doctor check?",
  "header": "Scope",
  "options": [
    {"label": "Everything (default)", "description": "Full system health — ~20s; runs all 15 categories"},
    {"label": "CC version & features only", "description": "Categories 10 + 13 + 14; ~3s — for 'is my CC up to date?'"},
    {"label": "MCP servers only", "description": "Category 12 (incl. pinning sub-check); ~5s — for 'are MCPs working?'"},
    {"label": "Plugin health only", "description": "Categories 0-3 + 5 (skills, agents, hooks, build); ~8s — for 'after npm run build'"}
  ]
}])

Skip the prompt entirely when the scope is unambiguous from the invocation. The fast scopes (3-8s) are 3-7× faster than the full run — voice users say "just the MCPs" and get a 5s answer.

Overview

The `/ork:doctor` command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 15 categories:

1. **Installed Plugins** - Detects ork plugin 2. **Skills Validation** - Frontmatter, references, token budget (dynamic count) 3. **Agents Validation** - Frontmatter, tool refs, skill refs (dynamic count) 4. **Hook Health** - Registration, bundles, async patterns 5. **Permission Rules** - Detects unreachable rules 6. **Schema Compliance** - Validates JSON files against schemas 7. **Coordination System** - Checks lock health and registry integrity 8. **Context Budget** - Monitors token usage against budget 9. **Memory System** - Graph memory health 10. **Claude Code Version** - Validates CC >= 2.1.220 (supported floor). Everything the old "recommends 2.1.154+" note gated (`xhigh` effort, `/ultrareview`, stream-json `plugin_errors`) is floor-guaranteed now, so there is nothing left to recommend 11. **External Dependencies** - Checks optional tool availability (agent-browser) 12. **MCP Status** - Active vs disabled vs misconfigured, API key presence for paid MCPs. CC 2.1.110: detects duplicate definitions across config scopes. Sub-check warns when HIGH-tier servers resolve to `@latest` in `.mcp.json` (closes #1462) 13. **Plugin Validate** - Runs `claude plugin validate` for official CC frontmatter + hooks.json validation (CC >= 2.1.77) 14. **Effort/Model Compatibility** - Warns only when `xhigh` effort is configured AND the active model is provably unable to run it. Silent otherwise, because the fallback itself is silent

When to Use

• After installing or updating OrchestKit
• When hooks aren't firing as expected
• Before deploying to a team environment
• When debugging coordination issues
• After running `npm run build`

Quick Start

/ork:doctor           # Standard health check
/ork:doctor -v        # Verbose output
/ork:doctor --json    # Machine-readable for CI

CLI Options

| Flag | Description | |------|-------------| | `-v`, `--verbose` | Detailed output per check | | `--json` | JSON output for CI integration | | `--category=X` | Run only specific category |

Health Check Categories

> **Detailed check procedures**: Load `Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/diagnostic-checks.md")` for bash commands and validation logic per category. > > **MCP-specific checks**: Load `Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/mcp-status-checks.md")` for credential validation and misconfiguration detection. > > **Output examples**: Load `Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/health-check-outputs.md")` for sample output per category.

Categories 0-3: Core Validation

| Category | What It Checks | Reference | |----------|---------------|-----------| | **0. Installed Plugins** | Auto-detects ork plugin, counts skills/agents | load `${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/diagnostic-checks.md` | | **1. Skills** | Frontmatter, context field, token budget, links, **activation-channel reachability** (no orphaned user-invocable skills) | load `${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/skills-validation.md` | | **2. Agents** | Frontmatter, model, skill refs, tool refs | load `${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/agents-validation.md` | | **3. Hooks** | hooks.json schema, bundles, async patterns — across all three hook scopes: **global**, **agent-scoped**, and **skill-scoped**. Detects the common hook problems: missing files (registered but not on disk), syntax errors in hooks.json or bundles, permission issues (non-e