OpenClaw Skill Not Loading — How to Diagnose and Fix It

Skills not loading is one of those problems that's usually a simple fix once you know where to look. Here's the systematic approach to diagnosing why a skill isn't working.

Understand How Skills Load

Skills aren't automatically active. They appear in the available_skills list injected into the agent's context. When a message matches a skill's description, the agent reads its SKILL.md and follows its instructions. Loading failures happen at one of these stages.

Step 1: Verify the Skill Directory Structure

# System skills location:
ls /usr/local/lib/node_modules/openclaw/skills/

# Custom workspace skills location:
ls ~/.openclaw/workspace/skills/

# Each skill should have its own folder with SKILL.md inside:
# skills/
#   my-skill/
#     SKILL.md
#     scripts/  (optional)
#     references/  (optional)

Step 2: Check SKILL.md Format

cat ~/.openclaw/workspace/skills/my-skill/SKILL.md

A valid SKILL.md has at minimum:

# My Skill Name

## Purpose
What this skill does (clear, single sentence).

## When to Use
Trigger conditions — what prompts should cause the agent to use this skill.

## Instructions
Step-by-step what the agent should do when this skill is invoked.

## Examples
Sample commands or invocations.

If the file is empty, malformed, or missing the Instructions section, the skill will load but fail to execute correctly.

Step 3: Verify the Skill Appears in Available Skills

# Ask the agent directly:
"What skills do you have available?"
"List your available skills with their descriptions."

# The agent should list your skill if it's in the correct location.

If your skill doesn't appear, it's a path or registration issue, not a content issue.

Step 4: Register Custom Skills (if needed)

Workspace skills need to be registered so they appear in the available_skills injection. Check how your system prompt or AGENTS.md references them:

# In some OpenClaw versions, you need to add skills to a skills registry:
# Check ~/.openclaw/workspace/AGENTS.md for skills configuration

# Example AGENTS.md skills entry:
## Available Skills
- my-skill: ~/.openclaw/workspace/skills/my-skill/SKILL.md

Step 5: Check for Path Issues

# Verify the SKILL.md file actually exists:
ls -la ~/.openclaw/workspace/skills/my-skill/SKILL.md

# Check file permissions:
# Should be readable:
# -rw-r--r-- 1 youruser staff 1234 Mar 27 10:00 SKILL.md

# Fix permissions if needed:
chmod 644 ~/.openclaw/workspace/skills/my-skill/SKILL.md

Step 6: Test the Skill Directly

# In Slack or chat, be explicit about which skill to use:
"Use the my-skill skill to [task]"

# Or read the skill file manually and follow it:
"Read the file at ~/.openclaw/workspace/skills/my-skill/SKILL.md and follow its instructions for [task]"

If the direct invocation works but natural triggering doesn't, the issue is in your skill's description — it's not matching the user's natural language. Make the description more specific and include example trigger phrases.

Step 7: Check for JavaScript or Script Errors

If your skill includes scripts in a scripts/ directory:

# Test the script directly:
node ~/.openclaw/workspace/skills/my-skill/scripts/main.js

# Check for syntax errors, missing dependencies, or permission issues
# Run with verbose output if available:
node --trace-uncaught ~/.openclaw/workspace/skills/my-skill/scripts/main.js

Step 8: Reinstall or Refresh the Skill

# For skills installed via clawhub:
npx clawhub install skill-name --force

# For custom skills, simply re-save the SKILL.md:
# (No gateway restart needed — skills are read on demand)

For the full guide to building and debugging OpenClaw skills — including advanced SKILL.md patterns, scripted skills, and the complete spec — The OpenClaw Playbook covers everything for $9.99.