OpenClaw skills extend functionality but can fail to load due to syntax errors in skill.md, missing npm/pip dependencies, file permission issues, or incorrect directory structure. When skills don't load, OpenClaw may start successfully but lack critical capabilities. This guide helps you diagnose and fix skill loading failures.
Why This Is Hard to Do Yourself
These are the common pitfalls that trip people up.
Malformed skill.md syntax
YAML frontmatter errors, invalid JSON, or incorrect metadata fields
Missing or incompatible dependencies
Required npm packages not installed, Python version mismatch, or conflicting versions
File permission errors
Skill files not readable by OpenClaw process user, or execute bit missing on scripts
Incorrect directory structure
skill.md in wrong location, missing index.js, or broken symlinks
Step-by-Step Guide
Check skill directory structure
Verify each skill follows the required file layout OpenClaw expects.
# List skill directories:
ls -la ~/.openclaw/skills/
# Each skill should have:
# skill-name/
# ├── skill.md (required: metadata + docs)
# ├── index.js (required: entry point)
# ├── package.json (optional: dependencies)
# └── README.md (optional: extra docs)
# Check a specific skill:
tree ~/.openclaw/skills/my-skill
# If tree isn't installed:
find ~/.openclaw/skills/my-skill -type fValidate skill.md syntax
Parse the skill.md file to find YAML frontmatter or JSON errors.
# Check for YAML syntax errors:
# Extract frontmatter (between --- markers)
awk '/^---$/,/^---$/{print}' ~/.openclaw/skills/my-skill/skill.md > /tmp/frontmatter.yml
yamllint /tmp/frontmatter.yml
# Common errors:
# - Missing closing ---
# - Incorrect indentation
# - Unquoted special characters
# - Duplicate keys
# Validate JSON blocks if present:
grep -A 100 "```json" ~/.openclaw/skills/my-skill/skill.md | grep -B 100 "```" | jq .
# Check required fields:
grep -E "^(name|version|description):" ~/.openclaw/skills/my-skill/skill.mdVerify file permissions
Ensure OpenClaw process can read skill files and execute scripts.
# Check ownership and permissions:
ls -la ~/.openclaw/skills/my-skill/
# OpenClaw process needs:
# - Read permission on skill.md, index.js
# - Execute permission on any shell scripts
# Fix permissions:
chmod 644 ~/.openclaw/skills/my-skill/skill.md
chmod 644 ~/.openclaw/skills/my-skill/index.js
chmod 755 ~/.openclaw/skills/my-skill/*.sh
# Fix ownership (replace with OpenClaw user):
sudo chown -R openclaw:openclaw ~/.openclaw/skills/Review skill loading logs
Check OpenClaw startup logs for specific skill errors or warnings.
# Filter logs for skill-related messages:
grep -i "skill" ~/.openclaw/logs/openclaw.log | tail -50
# Look for:
# - "Failed to load skill: my-skill"
# - "Syntax error in skill.md"
# - "Missing dependency"
# - "Skill disabled: incompatible version"
# Enable verbose skill logging:
export OPENCLAW_SKILL_DEBUG=true
systemctl restart openclaw
# Watch logs in real-time:
tail -f ~/.openclaw/logs/openclaw.log | grep skillTest skill in isolation
Load the skill manually to see detailed error messages.
# Create a test script:
cat > test-skill.js << 'EOF'
const fs = require('fs');
const path = require('path');
const skillPath = process.argv[2];
const skillMd = fs.readFileSync(
path.join(skillPath, 'skill.md'),
'utf8'
);
console.log('Skill content:', skillMd);
try {
const skill = require(path.join(skillPath, 'index.js'));
console.log('Skill loaded:', skill);
} catch (err) {
console.error('Failed to load:', err);
}
EOF
# Test the skill:
node test-skill.js ~/.openclaw/skills/my-skillReinstall skill dependencies
Ensure all npm or pip packages required by the skill are installed.
# For Node.js skills:
cd ~/.openclaw/skills/my-skill
# Remove old dependencies:
rm -rf node_modules package-lock.json
# Reinstall:
npm install
# Or if using specific registry:
npm install --registry=https://registry.npmjs.org/
# For Python skills:
cd ~/.openclaw/skills/my-skill
# Install requirements:
pip install -r requirements.txt
# Or in a virtual env:
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtSkills Still Not Loading?
Our OpenClaw skill experts debug broken plugins, write custom skills, and optimize skill performance. Get a curated skill library tailored to your automation needs.
Get matched with a specialist who can help.
Sign Up for Expert Help →