This identifies configuration errors in oh-my-claudecode environments and provides step-by-step instructions to fix them.
Install
mkdir -p .claude/skills/doctor && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2984" && unzip -o skill.zip -d .claude/skills/doctor && rm skill.zipInstalls to .claude/skills/doctor
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Diagnose and fix oh-my-claudecode installation issuesKey capabilities
- →Diagnose oh-my-claudecode plugin version drift
- →Identify legacy hook scripts in settings.json
- →Verify CLAUDE.md markers and companion file structure
- →Check Ruby dependency for Ralph workflows
- →Clean up stale plugin cache versions
How it works
The skill executes a series of diagnostic scripts to check file markers, plugin versions, and environment dependencies, then offers to remove legacy files or clear caches.
Inputs & outputs
When to use doctor
- →Fix broken oh-my-claudecode installation
- →Resolve configuration path issues
- →Troubleshoot environment setup
About this skill
Doctor Skill
Note: All ~/.claude/... paths in this guide respect CLAUDE_CONFIG_DIR when that environment variable is set.
Task: Run Installation Diagnostics
You are the OMC Doctor - diagnose and fix installation issues.
Step 1: Check Plugin Version
# Get installed and latest versions (cross-platform)
node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),d=process.env.CLAUDE_CONFIG_DIR||p.join(h,'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));console.log('Installed:',v.length?v[v.length-1]:'(none)')}catch{console.log('Installed: (none)')}"
npm view oh-my-claude-sisyphus version 2>/dev/null || echo "Latest: (unavailable)"
Diagnosis:
- If no version installed: CRITICAL - plugin not installed
- If INSTALLED != LATEST: WARN - outdated plugin
- If multiple versions exist: WARN - stale cache
Step 2: Check for Legacy Hooks in settings files
Read the profile-level ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json and the primary working directory's .claude/settings.json, then resolve every project-local settings file Claude Code may read before checking hooks. In a normal checkout, inspect the repository-root .claude/settings.local.json. In a linked Git worktree, inspect the main checkout root's .claude/settings.local.json, not just the linked worktree's file; identify the main checkout with git worktree list --porcelain. On Windows, and whenever Claude Code keeps the local file beside the shared .claude/settings.json, inspect .claude/settings.local.json beside that shared settings file, including in a worktree. Also inspect any starting-directory .claude/settings.local.json left by Claude Code versions before 2.1.211; Claude Code can still read it alongside the root file. Deduplicate identical paths. If the main checkout root or any applicable local settings file cannot be resolved or read, treat settings and script references as inconclusive and do not remove hooks or scripts. Check whether any applicable file has a "hooks" key with entries like:
bash ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/keyword-detector.shbash ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/persistent-mode.shbash ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/session-start.shbash ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/stop-continuation.shbash ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/silent-auto-update.sh
Also recognize standalone Node hook registrations under the active config directory's hooks/ folder: .mjs files named keyword-detector, persistent-mode, session-start, session-end, pre-tool-use, post-tool-use, post-tool-use-failure, code-simplifier, or stop-continuation. For the historical keyword-detector, persistent-mode, session-start, and stop-continuation basenames, .cjs and .js variants are legacy too. For example, node "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/keyword-detector.mjs" is a legacy registration. On Windows, recognize paths such as node "%USERPROFILE%\.claude\hooks\keyword-detector.mjs" and %CLAUDE_CONFIG_DIR%\hooks\<filename> (or their expanded absolute equivalents) with backslash separators as the same active config directory. Match only exact listed filenames invoked with node from that directory; do not match plugin-root commands or similarly named scripts in other directories.
A command is an auto-fix candidate only when it is a plain direct invocation of exactly one listed file: bash <exact .sh path>, node <exact Node path>, or the exact executable script path alone when the target has execute permission (for example, $HOME/.claude/hooks/keyword-detector.sh). No form may include extra arguments, shell operators, or other commands. If a command merely mentions the path, adds custom behavior (for example, bash legacy.sh && run-my-check), or cannot be parsed unambiguously, report it for manual cleanup and leave the hook object unchanged.
Before diagnosing a standalone registration as a duplicate, resolve plugin enablement with the runtime's precedence: managed and command-line settings first (read-only), then every applicable project-local settings file resolved above, then the primary working directory's ./.claude/settings.json, then ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json. Include the main-checkout, Windows side-by-side, and legacy starting-directory local paths when they apply. For duplicate keys between the root local file and a pre-2.1.211 starting-directory file, the root local value wins; never ignore a false from the effective local file or fall through to a project/profile true. The first scope that explicitly mentions any supported OMC ID decides; unmentioned scopes are transparent. The supported marketplace IDs are oh-my-claudecode, oh-my-claudecode@omc, and oh-my-claudecode@oh-my-claudecode. When the current session loads OMC from an inline source such as --plugin-dir, --plugin-url, or CLAUDE_CODE_PLUGIN_DIRS, also consider oh-my-claudecode@inline only after the active root's .claude-plugin/plugin.json has "name": "oh-my-claudecode" and the session source confirms that root is loaded. Treat that inline plugin as active for the session unless its manifest sets "defaultEnabled": false or an applicable settings source disables it; an explicit applicable true overrides the manifest default. CLAUDE_PLUGIN_ROOT is only a locator, not proof that a plugin is enabled; an explicit effective false always blocks automatic removal. Within each scope, enabledPlugins is canonical, and legacy plugins is consulted only if enabledPlugins does not mention any supported OMC ID. Thus a canonical false overrides a stale legacy true, and a higher-precedence false overrides any lower-precedence true. If applicable local sources conflict and the effective value cannot be determined, supported IDs in the winning field conflict, a relevant file is unreadable or malformed, or no effective enabled result can be established, treat plugin activity as inconclusive and do not auto-remove. Inspect every hook source for the active root read-only: the optional .claude-plugin/plugin.json hooks field accepts a path, an inline hooks object, or an array mixing paths and inline objects; resolve declared file paths relative to the plugin root and include hooks/hooks.json when present. A malformed, unreadable, or unresolved declared source makes event ownership inconclusive. A cached plugin version is insufficient. Also resolve the standalone script file and compare its bytes or SHA-256 with the shipped OMC payload for that exact filename; for historical .sh files, use the versioned fingerprints below. A matching name or path alone does not prove ownership. If the plugin is inactive, does not provide that event, no payload or fingerprint exists, the target cannot be read, or the content differs, treat the entry as potentially user-owned and do not recommend removal.
For known standalone payloads, verify the expected plugin event as well as the payload identity. The known OMC filename-to-event mapping is:
| Standalone payload basename | Canonical plugin event |
|---|---|
keyword-detector | UserPromptSubmit |
session-start | SessionStart |
session-end | SessionEnd |
pre-tool-use | PreToolUse |
post-tool-use | PostToolUse |
post-tool-use-failure | PostToolUseFailure |
persistent-mode, stop-continuation, code-simplifier | Stop |
For a historical payload, verify its event mapping from that version's trusted manifest or installer source; if unavailable, leave it for manual review. The active plugin must provide the canonical or specifically verified equivalent handler under the registration's event, and that handler must replace the payload's behavior. Merely finding any plugin handler for that event is insufficient. For example, a session-start script registered under Stop is not a duplicate even if the active plugin defines unrelated Stop handlers. If event or behavior equivalence is uncertain, preserve the hook and script.
The tracked historical OMC Bash-hook payload fingerprints (SHA-256) are:
keyword-detector.sh:abe4dd5e4b16231060166264d271a51e781f08a31c6aa402b26976f9c40d424e(96266316),748463911b2a8b7fffed51137c9731c962b656d490a1e4b27ef7ab10dbbbaff5(3a02feb1),1eaced21774916c31bec5b149a87009d014ffd8027ecf8e9d6ae6a36bdd79a40(bef486f1)persistent-mode.sh:c131c6846573f0f69b6e39aed1e6db8f05279131a8976f604c1511a46f564ce5(96266316),219e50bf42b7a7a0e52fb142844dce21faca7c327d9acf346fa70f074ac982ac(3a02feb1),02f4d0d63a9ce092fe5be02ce6e79f275710b773d4b8d75ff33f272540451eff(bef486f1)session-start.sh:d87571c326c43cc43b6948aca661a9616faa6943cfe1d1131f482bd30f638134(96266316),a9607c64a14d9f8e9fa990b9f38879ef095d85652f548b1232e28d14641214eb(3a02feb1),cf7aa2b008829784c8942766c3f00d348ef33a1aab66dd3f96536e95560fd56b(bef486f1)stop-continuation.sh:f74deb67479c7861b0966bc959ffd3917152b8872ac83d9243a03c7cb707b51f(96266316)
No tracked OMC payload fingerprint is available for silent-auto-update.sh or historical .js/.cjs variants. Treat those files as ownership-inconclusive; do not automatically remove their hook registrations or files.
For Node hooks, compare against the active plugin payload, any validated retained package under ${CLAUDE_CONFIG_DIR:-~/.claude}/plugins/cache/omc/oh-my-claudecode/<version>/, and the adjacent node-hook-fingerprints.json index. The index records SHA-256 fingerprints with exact stable release-tag provenance for every shipped Node module under templates/hooks/**/*.mjs, including hook helpers; search by payload path and inspect only that block rather than loading the entire index. If it is missing, malformed, or has no matching fingerprint, leave the entry for manual review. P
Content truncated.
When not to use it
- →Troubleshooting issues unrelated to oh-my-claudecode
- →Modifying user-defined custom agents or commands
Prerequisites
Limitations
- →Requires user confirmation for automated fixes
- →Cannot automatically resolve custom user agent conflicts
How it compares
It provides targeted, automated remediation for specific oh-my-claudecode configuration issues instead of generic troubleshooting.
Compared to similar skills
doctor side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| doctor (this skill) | 1 | 6mo | Caution | Beginner |
| network-info | 3 | 8mo | Review | Beginner |
| debug-cluster | 2 | 12mo | Review | Intermediate |
| replit-advanced-troubleshooting | 0 | 4mo | Caution | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by Yeachan-Heo
View all by Yeachan-Heo →You might also like
network-info
UKGovernmentBEIS
Gather network configuration and connectivity information including interfaces, routes, and DNS
debug-cluster
openshift
Provides systematic debugging approaches for HyperShift hosted-cluster issues. Auto-applies when debugging cluster problems, investigating stuck deletions, or troubleshooting control plane issues.
replit-advanced-troubleshooting
jeremylongshore
Apply Replit advanced debugging techniques for hard-to-diagnose issues. Use when standard troubleshooting fails, investigating complex race conditions, or preparing evidence bundles for Replit support escalation. Trigger with phrases like "replit hard bug", "replit mystery error", "replit impossible to debug", "difficult replit issue", "replit deep debug".
devops-troubleshooter
sickn33
Expert DevOps troubleshooter specializing in rapid incident response, advanced debugging, and modern observability. Masters log analysis, distributed tracing, Kubernetes debugging, performance optimization, and root cause analysis. Handles production outages, system reliability, and preventive monitoring. Use PROACTIVELY for debugging, incident response, or system troubleshooting.
vastai-common-errors
jeremylongshore
Diagnose and fix Vast.ai common errors and exceptions. Use when encountering Vast.ai errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "vastai error", "fix vastai", "vastai not working", "debug vastai".
environment-triage
parcadei
Environment Triage