You installed a skill but OpenClaw can't find it. Or it loads but doesn't work. Or it conflicts with another skill. This troubleshooting guide covers the 15 most common reasons skills fail to load — with exact diagnostic commands and copy-paste fixes for every scenario.
Before diving into troubleshooting, run these three commands:
1. Check installed skills:
`npx clawhub@latest skills list`
Look for your skill in the output. If it's not listed, it wasn't installed. Re-install: `npx clawhub@latest install
Fix 1: Workspace vs global path confusion
OpenClaw loads skills from two locations: `~/.openclaw/skills/` (global) and `./.openclaw/skills/` (workspace). If you installed a skill globally but you're running OpenClaw from a workspace that has a `.openclaw/` directory, the workspace config might override global settings.
Diagnostic: `npx clawhub@latest config paths` shows which directories OpenClaw is scanning.
Fix: Install the skill in the correct scope: `--global` for global, `--local` for workspace.
Fix 2: Symlink issues on macOS
If you installed Node.js via Homebrew and OpenClaw via npx, symlink paths may not resolve.
Fix: `npx clawhub@latest doctor` detects and fixes symlink issues.
Fix 3: WSL path mismatch
On Windows WSL, if you installed the skill from the Windows filesystem (`/mnt/c/...`) but run OpenClaw from the Linux filesystem (`~/...`), paths won't resolve.
Fix: Always install and run from the Linux filesystem. See our Windows install guide.
Fix 4: Docker volume not mounted
If running in Docker, your skills directory must be mounted: `-v ~/.openclaw:/root/.openclaw`.
Fix: Restart the container with the correct volume mount.
Fix 5: Corrupted SKILL.md
If the SKILL.md has YAML parsing errors, OpenClaw silently skips it.
Fix: Validate the file: `npx clawhub@latest validate ~/.openclaw/skills/
Fix 6: Skill precedence conflict
If two skills define tools with the same name, the later-loaded skill wins. Your skill might be loaded but its tools are shadowed.
Diagnostic: `npx clawhub@latest skills tools` lists all loaded tools and which skill owns them.
Fix: Rename conflicting tools or disable the competing skill.
Fix 7: Dependency not installed
Some skills depend on other skills. If the dependency is missing, the skill fails to load.
Diagnostic: Check the SKILL.md frontmatter for `dependencies`. Install missing dependencies.
Fix 8: Version incompatibility
A skill built for OpenClaw 3.x may not work with 4.x due to breaking changes.
Fix: Check the skill's compatibility notes. Update the skill: `npx clawhub@latest update
Fix 10: Node.js version too old OpenClaw 4.x requires Node.js 20+. Skills may use features unavailable in older versions. Fix: `nvm install 20 && nvm use 20` Fix 11: Missing system binary Skills that use system commands (Docker, git, kubectl) require those binaries to be installed. Diagnostic: Check the error message for 'command not found'. Fix: Install the required binary. Fix 12: Memory limit exceeded Too many active skills can exceed Node.js's default memory limit. Fix: Reduce active skills to 5-10, or increase memory: `NODE_OPTIONS='--max-old-space-size=4096' npx clawhub@latest` Fix 13: Network blocking Skills that need network access won't work behind strict firewalls or in `--network=none` Docker containers. Fix: Configure network rules to allow the skill's required domains. See our security guide for whitelisting. Fix 14: Stale cache OpenClaw caches skill metadata. After updates, the cache may be stale. Fix: `npx clawhub@latest cache clear` then restart. Fix 15: Refresh / restart needed The most common fix: skills are loaded at startup. After installing or updating, you must restart OpenClaw. Fix: Restart OpenClaw, or type `/reload` in interactive mode.
My skill works in interactive mode but not in cron jobs. Why?
Cron jobs use a different PATH and environment. Ensure the cron entry includes the full path to Node.js and OpenClaw, and that `~/.openclaw` is accessible from the cron user.
The skill loaded yesterday but not today. What changed?
Most likely an auto-update changed the skill. Check `~/.openclaw/logs/` for update records. Pin versions to prevent unexpected changes: `npx clawhub@latest install