How to Debug Skill Loading Issues in OpenClaw

You’re ready to extend OpenClaw with a new skill, but something’s wrong—the CLI doesn’t see it, or you get cryptic errors on launch. Don’t panic. Skill loading issues are common, especially during setup or when syncing custom scripts across devices, but they’re usually straightforward to resolve with the right tools.

This guide walks you through the most frequent root causes and how to diagnose them using OpenClaw’s built-in tooling.

Step 1: Verify the Skill is in the Right Location

OpenClaw scans three locations for skills:

1. Bundled skills (<install_dir>/skills/)
2. Workspace skills (<workspace>/skills/)
3. Managed overrides (<workspace>/.skills/)

If you’re developing or installing a skill manually, it should live in your workspace’s skills/ directory. Ensure the skill folder is named correctly and contains a SKILL.md file:

ls -la ~/.openclaw/workspace/skills/debugging-tips/
# Should show: SKILL.md, and any supporting scripts or assets

💡 Tip: Use openclaw skills list to see which directories are being scanned and which skills are detected.

Step 2: Check for Missing Dependencies

Some skills require external CLIs or system tools (e.g., peekaboo, blu, remindctl). If these aren’t installed or aren’t in your PATH, OpenClaw will list the skill as ineligible.

Run:

openclaw skills check

This outputs a breakdown of all skills and their readiness. Look for your skill under "Missing Requirements". If it’s there, install the needed tools. For example:

brew install peekaboo  # macOS requirement for UI automation

Step 3: Use skills info to Inspect

Once the skill is in place and dependencies are installed, inspect it directly:

openclaw skills info debugging-tips

This shows:

• Description and location
• Required tools and environment state
• Whether it’s eligible to load
• Last modified timestamp

If the output says "Not eligible", recheck dependencies and file permissions.

Step 4: Validate SKILL.md

A malformed SKILL.md can prevent loading. Ensure the file:

• Is in the correct directory
• Has proper YAML frontmatter (if used)
• Defines a valid <name>, <description>, and <location>
• Uses correct relative paths for scripts or assets

Example minimal SKILL.md:

# SKILL.md - Debugging Tips

<skill>
  <name>debugging-tips</name>
  <description>Provide guidance on diagnosing common OpenClaw issues.</description>
  <location>/Users/jorden/.openclaw/workspace/skills/debugging-tips</location>
</skill>

Step 5: Restart and Recheck

After fixes, restart the Gateway to reload skills:

openclaw gateway restart

Then run:

openclaw skills list --eligible

Your skill should now appear in the list.

Common Pitfalls

• File permissions: Ensure scripts are executable (chmod +x script.sh)
• Symlink issues: Avoid broken or circular symlinks in skill paths
• Node.js version: Some CLI tools require Node 22+; verify with node -v
• Workspace drift: If using sync (e.g., Git), ensure all devices have the same structure and paths

Final Check: Test with sessions_spawn

Once loaded, test the skill in isolation:

openclaw agent --message "Show debugging tips for missing tools" --model llama

If it runs without errors, you’re good to go.

Conclusion

Skill loading issues are rarely deep bugs—they’re usually path, permissions, or dependency gaps. Use openclaw skills commands to inspect, fix, and reload. With a bit of patience, your new skill will be active and ready to automate.