Fix: Installed Skills Not Showing in OpenClaw (Common Gotchas)

You've dropped a skill folder into ~/.openclaw/workspace/skills/, restarted the gateway, but openclaw skills list shows... nothing. Sound familiar? This is one of the most common issues new users hit, and it's almost always one of these three things.

The Quick Checklist

1. Verify Your Workspace Path

First, confirm what OpenClaw thinks your workspace is:

openclaw config get agents.defaults.workspace

Skills must be in one of these locations:

• Per-agent: <workspace>/skills/<skill-name>/SKILL.md
• Shared: ~/.openclaw/skills/<skill-name>/SKILL.md

2. Check That SKILL.md Exists at the Right Depth

The most common issue: your skill folder exists, but there's no SKILL.md at the folder root (or it's nested deeper).

find ~/.openclaw/workspace/skills -maxdepth 2 -name SKILL.md -print

If this prints nothing, that's your problem. The skills loader requires a SKILL.md file directly inside each skill folder.

3. Check for Parse Errors

If SKILL.md exists but still doesn't load, it's likely a parsing issue. The skills loader is picky:

• Must have YAML frontmatter (the --- delimiters)
• name: and description: must be simple single-line values
• metadata: must be a single-line JSON object (multi-line YAML metadata gets skipped)

Check logs for errors:

openclaw logs --limit 300 | grep -i skill

Pro Tip: stderr Gotcha

If openclaw skills list | grep your-skill shows nothing but the command works without grep, try:

openclaw skills list 2>&1 | grep -i your-skill

Some CLI output goes to stderr, which grep doesn't see by default.

Still Stuck?

Use the verbose check:

openclaw skills check -v

This often reveals exactly why a skill isn't loading.

Based on a community discussion in #help - thanks to Khmorr for surfacing this common issue and Krill for the detailed troubleshooting steps.