How to use the OMC Doctor skill to diagnose oh-my-claudecode

What an agent skill is and what omc-doctor does

An agent skill is a folder containing a SKILL.md file that gives an AI coding agent specific instructions for a task. When a request matches the skill, the agent follows those instructions instead of working from general knowledge alone.

The omc-doctor skill covers installation diagnostics for oh-my-claudecode. It checks the installed plugin version against the latest version published on npm. It also inspects Claude Code settings files for hook registrations left over from older releases of the plugin. The skill is designed to fix only clearly identified legacy entries and to leave anything ambiguous alone, reporting it for manual cleanup instead.

• Checks the installed plugin version and reports if none is found, if the plugin is outdated, or if several versions are cached.
• Looks for legacy hook entries in your settings files and in project-local settings files.
• Checks whether a standalone hook script really belongs to oh-my-claudecode before recommending removal.
• Reports anything it cannot classify confidently for you to review by hand.

Install the omc-doctor skill with a ZIP or the Claude apps

Download the ZIP for the omc-doctor skill from this page. You can install it in one of two ways, depending on how you use Claude.

For Claude Code, unzip the download into your personal skills folder at ~/.claude/skills/. To make the skill available only inside one project, unzip it into that project's .claude/skills/ folder instead.

In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal use across projects: unzip into ~/.claude/skills/.
• Single project only: unzip into the project's .claude/skills/ folder.
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP.

What you need before running the health check

The skill depends on a few tools being available. The version check runs node and npm, so Node.js and npm must be installed. Claude Code must also have the oh-my-claudecode plugin installed, because the skill inspects that plugin's cache and settings. The latest-version lookup needs network access to the npm registry.

The skill is specific to oh-my-claudecode. If you have not installed that plugin, the checks will not apply to your setup.

• Node.js and npm
• Claude Code with the oh-my-claudecode plugin installed
• Network access to the npm registry

Ask the agent for a health check

You do not need to type a special command. Describe the problem or ask for a check in plain language, and the agent should pick up the skill when the request matches its purpose. Ask for a diagnosis first, before any fixes.

Good requests name the plugin and the symptom. Examples include asking the agent to check whether oh-my-claudecode is outdated, to look for duplicate or legacy hooks, or to audit your Claude Code settings files and list anything that looks like a leftover from an older release.

The version check the skill runs is roughly equivalent to this, where the second line queries the latest published version:

• Check my oh-my-claudecode install. Is the plugin outdated?
• I'm seeing duplicate hooks in Claude Code. Look for legacy hook entries in my settings.
• Audit my Claude Code settings files for old oh-my-claudecode hook registrations and tell me what you would remove, but don't change anything yet.

Read the diagnosis and decide on fixes

The skill reports its findings using three levels. A missing installation is critical. An installed version that differs from the latest is a warning about an outdated plugin. Multiple cached versions are a warning about a stale cache.

For hooks, the skill only treats a command as an auto-fix candidate when it is a plain, direct invocation of one listed hook file. Anything that mentions a path without running it cleanly, adds extra arguments, chains other commands, or cannot be parsed clearly is left unchanged and listed for manual cleanup. Read the report before approving edits to your settings files.

• CRITICAL: plugin not installed.
• WARN: installed version differs from the latest version.
• WARN: multiple versions exist, which suggests a stale cache.
• Manual cleanup: entries the skill cannot classify with confidence are reported, not removed.

Safety notes: scripts, network and settings edits

This skill runs scripts and uses the network. It runs a Node command to read the plugin cache and an npm command to look up the latest version. It reads settings.json and local settings files, and it can remove hook entries it classifies as legacy. Review every proposed change, and keep a backup of your settings files if you want an easy way back.

The skill is not suitable for people who are not comfortable reviewing changes to settings.json or hook files. The skill text also sets out cautious rules, including not removing anything when a settings file is unreadable or when plugin enablement is unclear. Those rules only help if you read what the agent proposes.

The skill text we reviewed ends mid-sentence in its final rules, so read the full SKILL.md file yourself before running the skill on a real setup.

• Runs scripts: yes.
• Uses the network: yes, for the npm registry lookup.
• Edits configuration: it can remove entries it classifies as legacy, so review changes first.

Tips for getting useful results

Ask for a read-only audit first. This lets you see what the skill would change before any file is edited. If you use git worktrees, mention that in your request, because the skill checks the main checkout's local settings as well as the current folder's.

If you use a custom Claude configuration directory, the skill's paths respect the CLAUDE_CONFIG_DIR environment variable when it is set.

• Start with a read-only request, then approve specific changes.
• Mention git worktrees if you use them.
• Keep a copy of settings files before approving removals.