OrchestKit Health Diagnostics Skill

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 16 categories:

Installed Plugins - Detects ork plugin
Skills Validation - Frontmatter, references, token budget (dynamic count)
Agents Validation - Frontmatter, tool refs, skill refs (dynamic count)
Hook Health - Registration, bundles, async patterns
Permission Rules - Detects unreachable rules
Schema Compliance - Validates JSON files against schemas
Coordination System - Checks lock health and registry integrity
Context Budget - Monitors token usage against budget
Memory System - Graph memory health
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
External Dependencies - Checks optional tool availability (agent-browser)
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)
Plugin Validate - Runs claude plugin validate for official CC frontmatter + hooks.json validation (CC >= 2.1.77)
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
Sandbox Posture - CC Bash-sandbox on/off in settings.local.json, with a /sandbox nudge
Operator Settings Posture - Detects security controls that a plugin bundle cannot carry (credential-read deny rules, the sandbox block, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) and are therefore missing unless the operator wrote them into their own settings

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-executable scripts), and stale references (entries pointing at renamed/removed handlers) | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/hook-validation.md |

Activation-channel orphans (repo / pre-release): a user-invocable skill should be reachable by more than a human typing it — via a chain (another skill references /ork:<skill>), a subagent grant (skills: in src/agents/*.md), or a background trigger. A skill with none is an "island" that silently rots. In a repo checkout, run npm run test:manifests:channels (gated in CI via test:manifests). Fix an island by wiring any one channel, or add it to STANDALONE_ALLOWLIST with a justification.

Categories 4-5: System Health

| Category | What It Checks | Reference | |----------|---------------|-----------| | 4. Memory | .claude/memory/ graph integrity + queue depth; auto-memory MEMORY.md index budget (≤24.4 KB; warns + recommends /ork:dream on re-bloat) | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/memory-health.md | | 5. Build | plugins/ sync with src/, manifest counts, orphans | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/diagnostic-checks.md |

Analytics writer liveness (System Health): the local analytics pipeline has several independent JSONL writers under ~/.claude/analytics/ (skill-usage, agent-usage, hook-timing). A writer can die silently while its siblings stay hot — observed once for four months (skill-usage.jsonl, 2026-03 to 2026-07). The check is a peer comparison: flag any watched file whose last write is ≥48h old while a sibling wrote within 24h (stat -f '%m %N' ~/.claude/analytics/*.jsonl). The lifecycle/analytics-liveness-check SessionStart hook runs the same comparison continuously.

A flagged writer means the write path was dropped from dispatch, so check both surfaces — src/hooks/hooks.json AND the entries map (src/hooks/src/entries/*.ts). A hook present in one but not the other is registered-looking and silently dead: the #959 failure class. /ork:telemetry-inspect gives the per-file deep dive, including the field-level defects tracked in #3034 (constant fields) and #3035 (phantom rows), which this structural check cannot see.

(Category numbering in this file is inconsistent between the Overview list above and these tables — the Overview numbers 4 as Hook Health, the tables number 4 as Memory. This check belongs to System Health regardless of which numbering a reader follows.)

Categories 6-9: Infrastructure

| Category | What It Checks | |----------|---------------| | 6. Permission Rules | Unreachable rules detection | | 7. Schema Compliance | JSON files against schemas | | 8. Coordination | Multi-worktree lock health, stale locks, sparse paths config | | 9. Context Budget | Token usage against budget |

Categories 10-16: Environment

| Category | What It Checks | Reference | |----------|---------------|-----------| | 10. CC Version | Runtime version against minimum required | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/version-compatibility.md | | 11. External Deps | Optional tools (agent-browser, portless) | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/diagnostic-checks.md | | 12. MCP Status | Enabled/disabled state, credential checks, HIGH-tier @latest pinning warn | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/mcp-status-checks.md + ${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/mcp-pinning-check.md | | 13. Plugin Validate | Official CC frontmatter + hooks.json validation (CC >= 2.1.77) | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/diagnostic-checks.md | | 14. Effort/Model | xhigh effort configured on a model that provably cannot run it (see below). Defaults to silence | inline | | 15. Sandbox Posture | CC Bash-sandbox on/off + /sandbox nudge (opt-in, Bash-only; info-level) | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/sandbox-posture.md | | 16. Operator Settings Posture | Controls a plugin bundle cannot carry, so they exist only if the operator wrote them: credential-read permissions.deny rules (zero hook coverage, measured), the sandbox block incl. network.deniedDomains (the egress guard only asks on the upload shape; a plain GET abstains), and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS (ork's own agent-teams.ts gates on it). Warn-level; prints the JSON to paste | load ${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/settings-posture.md |

Why Check 16 exists at all: plugins-reference.md:858 says "Only the agent and subagentStatusLine keys are currently supported" in a plugin's bundled settings.json. Everything else ork used to declare there was inert, so the protection it looked like it shipped was never in force. Check 16 is the replacement: detect the gap in a scope CC really reads, then hand the operator the exact JSON. The ork:configure skill, section Operator-Scope Settings, carries the paste-ready blocks.

Category 14: Effort/Model Compatibility (CC 2.1.111+)

CC 2.1.111 added the xhigh effort tier. The only reason this category exists is the silence: a model that does not implement xhigh degrades the request to high with no error, no warning, and no log line, so the extra deepening pass the affected skills document is lost without any visible signal. If CC ever surfaces the downgrade itself, delete this category.

The check is capability-shaped, not model-name-shaped. Never hardcode "the current frontier model" here: that guarantees a false failure the day the next one ships, and it prescribes a downgrade to a superseded model.

Do not route this through src/hooks/src/lib/models.vocab.json. That file is the model-id/pricing vocabulary and carries no effort or capability fields at all, so keying off it would leave the check permanently, accidentally dead rather than deliberately quiet.

Detection (warn only on positive proof):

Resolve the configured effort, in order: .claude/settings.json → effort, then $ORCHESTKIT_EFFORT (populated by the effort-detector hook), then any .claude/chain/*.json entry that explicitly set effort: xhigh. No xhigh anywhere means pass, no output.
Resolve the active model id.
Warn only when that model id matches a prefix in doctor's local XHIGH_UNSUPPORTED_PREFIXES table below. Every other outcome (model absent from the table, model id unresolvable, settings file missing) is a pass. A check that cannot prove a problem stays quiet.

# Doctor-local capability table. Deliberately a DENY-list, not an allow-list:
# a model absent from this table is assumed to support xhigh and emits nothing.
# Add an entry only from an OBSERVED silent degrade, citing the CC version it was
# seen on. Never add one by inferring from a model being new, old, or cheap.
XHIGH_UNSUPPORTED_PREFIXES = [
    # prefix        evidence
    "claude-3-",  # the whole Claude 3 line predates CC 2.1.111, which introduced the tier
]

An empty or short table is the correct resting state. Silence here means "doctor has no proof of a problem", which is a true statement, whereas a name-matched failure against an unrecognized model is a false one.

Warning format (no model name is hardcoded, both sides are read at runtime):

WARNING: effort is set to `xhigh`, but <model-id> matches XHIGH_UNSUPPORTED_PREFIXES.
  Configured effort: xhigh (source: <settings.json | $ORCHESTKIT_EFFORT | chain>)
  Impact: the run degrades to `high` with no error and no log line, so the extra
          deepening pass is lost with nothing to notice it by.
  Fix: run this on a model that implements `xhigh`, or set effort to `high` so the
       config matches what actually executes.

Exit code: Non-zero in --json mode only when the warning actually fires; soft warning in interactive mode. A silent pass is exit 0.

Report Format

Every category reports an explicit pass / warn / fail status, and every warn or fail comes with specific fix steps for that failure type (the exact command to run, file to edit, or config to change) — doctor diagnoses AND prescribes, it never just lists problems.

Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/report-format.md") for ASCII report templates, JSON CI output schema, and exit codes.

Interpreting Results & Troubleshooting

Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/remediation-guide.md") for the full results interpretation table and troubleshooting steps for common failures (skills validation, build sync, memory).

Bisect with --safe-mode (CC 2.1.169+): when doctor findings don't explain a misbehaving session, restart with claude --safe-mode (or CLAUDE_CODE_SAFE_MODE=1) — it disables ALL customizations (CLAUDE.md, plugins incl. ork, skills, hooks, MCP). If the problem disappears, it's a customization; re-enable halves to isolate. If it persists, it's CC itself — file upstream.

After you fix an issue

CC 2.1.69+: Run /reload-plugins to activate plugin changes in the current session without restarting.

CC 2.1.116+: /reload-plugins and background plugin auto-update now auto-install missing plugin dependencies from marketplaces you've already added. If ork:doctor flagged a plugin-load failure due to a missing dep, /reload-plugins resolves it in place — no manual plugin install step needed.

CC 2.1.152+: For non-plugin skills in a skill directory (~/.claude/skills/ or .claude/skills/), run /reload-skills to re-scan without restarting — the skill analogue of /reload-plugins.

Chain: Deeper Audit

After a clean health report, audit the observability pipeline itself:
/ork:telemetry-inspect
doctor validates structure (manifests, hooks, skills, agents); /ork:telemetry-inspect validates the data plane — every telemetry writer's row count, schema lock, growth trend, and orphaned analytics files that structural checks don't cover.

Related Skills

ork:configure - Configure plugin settings
ork:telemetry-inspect - Audit the telemetry/analytics pipeline after a clean structural check
ork:quality-gates - CI/CD integration
security-scanning - Comprehensive audits

References

Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/<file>") or Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/<file>"): | File | Content | |------|---------| | rules/diagnostic-checks.md | Bash commands and validation logic per category | | rules/mcp-status-checks.md | Credential validation and misconfiguration detection | | references/remediation-guide.md | Results interpretation and troubleshooting steps | | references/health-check-outputs.md | Sample output per category | | references/skills-validation.md | Skills frontmatter and structure checks | | references/agents-validation.md | Agents frontmatter and tool ref checks | | references/hook-validation.md | Hook registration and bundle checks | | references/memory-health.md | Memory system integrity checks | | references/permission-rules.md | Permission rule detection | | references/schema-validation.md | JSON schema compliance | | references/report-format.md | ASCII report templates and JSON CI output | | references/version-compatibility.md | CC version and channel validation | | references/mcp-pinning-check.md | HIGH-tier MCP @latest warning logic + tier source-of-truth | | references/sandbox-posture.md | CC Bash-sandbox on/off detection + /sandbox nudge (Check 15) | | references/settings-posture.md | Operator-scope security posture: what a plugin bundle cannot carry, and how to detect it missing (Check 16) |

Agent Skills: OrchestKit Health Diagnostics

Install this agent skill to your local

Skill Files