Claw Mart Skills Not Loading: Fix Guide

You installed a skill from Claw Mart, dropped it into your OpenClaw workspace, and… nothing. Your agent doesn't mention it. Doesn't use it. Acts like it doesn't exist. You check the file — it's there. You paste the instructions again — the agent nods politely and then ignores them on the next turn.

This is the single most common issue people hit when setting up OpenClaw skills, and it's almost never a bug. It's a configuration problem. The skill file is in the wrong place, the agent doesn't know to look for it, or there's a loading order conflict that silently swallows it.

I've debugged this dozens of times — for my own agents and for people setting up skills from Claw Mart. The fix is usually fast once you know where to look. Let's walk through every cause I've seen, how to diagnose it, and how to make sure your skills load reliably every single time.

How OpenClaw Skills Actually Load

Before we fix anything, you need a mental model of how OpenClaw discovers and loads skill files. Without this, you're just guessing.

When your OpenClaw agent starts a session, it reads from a specific set of files in your workspace directory. The core ones are:

SOUL.md — The agent's personality, voice, and behavioral rules
AGENTS.md — What tools, APIs, and CLIs the agent has access to
MEMORY.md — Persistent knowledge and context
SKILL.md files — Individual capabilities, workflows, and procedures

The key thing: OpenClaw doesn't magically spider your entire filesystem looking for skill files. It reads from known locations in a known order. If your skill file isn't where the agent expects it, it simply doesn't exist as far as the agent is concerned.

This is actually a good design — you don't want your agent loading random files — but it means you need to be deliberate about where you put things.

Problem 1: The Skill File Is in the Wrong Directory

This accounts for probably 60% of all "skills not loading" reports. You download a skill from Claw Mart, unzip it, and drop it somewhere reasonable-looking. But "reasonable-looking" and "where OpenClaw actually reads from" are different things.

The fix:

Skills need to live inside your OpenClaw workspace directory. The typical structure looks like this:

~/clawd/
├── SOUL.md
├── AGENTS.md
├── MEMORY.md
├── skills/
│   ├── email-fortress/
│   │   └── SKILL.md
│   ├── coding-loops/
│   │   └── SKILL.md
│   ├── autonomy-ladder/
│   │   └── SKILL.md
│   └── twitter-agent/
│       └── SKILL.md
└── cron/

If you dropped your skill file in ~/Downloads/ or ~/Documents/skills/ or anywhere outside the workspace tree, your agent will never see it.

Diagnostic step: Open a terminal and check:

# Find where your OpenClaw workspace lives
ls ~/clawd/skills/

# Or if you customized the path:
ls $OPENCLAW_HOME/skills/

If your skill directories are empty or missing, that's your answer. Move the files:

# Example: moving a downloaded skill into place
mkdir -p ~/clawd/skills/email-fortress
cp ~/Downloads/email-fortress/SKILL.md ~/clawd/skills/email-fortress/

Problem 2: The Agent Doesn't Know the Skill Exists

Here's a subtle one. The file is in the right place, but your agent's core instructions don't reference it. Some OpenClaw setups require you to register skills — either by listing them in SOUL.md or AGENTS.md, or by including an explicit reference.

Think of it this way: your agent reads SOUL.md first. If SOUL.md says "you have these capabilities," the agent builds its self-model from that list. A skill file sitting in a subdirectory that's never mentioned is like a book on a shelf that nobody told you about. It's technically accessible, but you'd never reach for it.

The fix:

Open your SOUL.md and make sure it references your installed skills. You don't need to paste the entire skill content — just tell the agent where to look:

## Skills

You have the following skills installed. Read the SKILL.md in each directory before performing related tasks:

- skills/email-fortress/ — Email security and triage
- skills/coding-loops/ — Persistent coding agent sessions
- skills/autonomy-ladder/ — Tiered decision framework
- skills/twitter-agent/ — X/Twitter posting and engagement
- skills/nightly-build/ — Self-improvement during off-hours
- skills/access-inventory/ — Tool and API tracking

This is a one-time setup step, but people skip it because they assume the agent will auto-discover everything. It won't. Be explicit.

Problem 3: Filename or Formatting Issues

I've seen this more than I'd like to admit: the skill file is named Skill.md or skill.MD or SKILLS.md (plural) instead of the expected SKILL.md. File systems can be case-sensitive. OpenClaw looks for specific filenames.

The fix:

# Check exact filenames in your skills directories
find ~/clawd/skills/ -type f -name "*.md" | sort

Make sure every skill directory contains a file named exactly SKILL.md — uppercase, singular, with the .md extension. Not .txt. Not .markdown. Not .MD.

While you're at it, check for hidden characters. If you created the file on Windows and moved it to a Linux/macOS environment, you might have carriage return characters (\r) gunking things up:

# Check for Windows line endings
file ~/clawd/skills/email-fortress/SKILL.md
# Should say "ASCII text" or "UTF-8 Unicode text"
# If it says "with CRLF line terminators", fix it:
sed -i 's/\r$//' ~/clawd/skills/email-fortress/SKILL.md

Problem 4: Context Window Overflow

This one's sneaky because everything looks correct. Files are in the right place, names are right, SOUL.md references them — but the agent still doesn't use the skill, or uses it inconsistently.

The likely cause: you've loaded so many skills that the combined context overflows what the agent can hold in working memory. When that happens, skills loaded last get silently dropped or only partially read. The agent has technically "seen" the file but hasn't retained enough of it to actually follow the procedures.

The fix:

Two options here.

Option A: Lazy loading. Instead of having your agent read every skill file at session start, tell it to read specific skills on demand:

## Skills (load on demand)

When a task involves email, read skills/email-fortress/SKILL.md first.
When a task involves coding agents, read skills/coding-loops/SKILL.md first.
When a task involves Twitter/X, read skills/twitter-agent/SKILL.md first.

This keeps your baseline context lean and only pulls in skill details when they're relevant.

Option B: Consolidate. If you're running five or six skills, the combined SKILL.md files might have redundant sections. Some skills — like the Autonomy Ladder, Access Inventory, and Nightly Self-Improvement — work together as a system. This is actually why Felix's OpenClaw Starter Pack exists. Those six skills are already designed to work as a unified system rather than six standalone files competing for context space. They share conventions, reference each other, and avoid redundant instructions. If you're installing skills piecemeal and running into context issues, the Starter Pack is worth looking at just for the integration alone.

Problem 5: Skill Conflicts and Override Issues

You installed two skills that both define how the agent should handle email. Or you have an autonomy rule in SOUL.md that contradicts the Autonomy Ladder skill. Or a memory instruction in one skill file conflicts with your Three-Tier Memory System setup.

When agents encounter contradictory instructions, they don't throw an error. They just pick one interpretation — usually whatever they read most recently — and quietly ignore the other. This looks like a skill "not loading" when really it's loading fine but being overridden.

The fix:

Audit for contradictions. Grep is your friend:

# Find all rules about email across your workspace
grep -r -i "email" ~/clawd/SOUL.md ~/clawd/skills/*/SKILL.md

# Find all autonomy/permission rules
grep -r -i "autonomy\|permission\|tier\|escalat" ~/clawd/SOUL.md ~/clawd/skills/*/SKILL.md

# Find all memory-related instructions
grep -r -i "memory\|remember\|knowledge" ~/clawd/SOUL.md ~/clawd/skills/*/SKILL.md

Look for conflicting directives. Common culprits:

SOUL.md says "always ask before acting" while Autonomy Ladder says "Tier 1: act and report"
A generic email rule in SOUL.md contradicts Email Fortress's security boundaries
Multiple skills defining different memory formats or storage locations

The solution is to pick one source of truth per domain. If you're using the Autonomy Ladder skill, remove any autonomy rules from SOUL.md and defer to the skill. If Email Fortress handles email, take email rules out of your base configuration.

Problem 6: Cron-Dependent Skills Not Triggering

Some skills — like the Nightly Self-Improvement or Morning Briefing System — aren't meant to run during conversation. They're triggered by cron jobs or heartbeat schedules. If you're waiting for your agent to spontaneously perform a nightly review during a 2 PM chat session, it's not going to happen. It's not a loading issue; it's a triggering issue.

The fix:

Check your cron configuration:

# View your OpenClaw cron setup
crontab -l

# Or check the cron directory
ls ~/clawd/cron/
cat ~/clawd/cron/*.md

If there's no cron entry for the skill, it won't run on schedule. The typical setup for a nightly skill looks something like this:

# Run nightly self-improvement at 3 AM
0 3 * * * cd ~/clawd && openclaw run skills/nightly-build/SKILL.md

For the Morning Briefing System, you'd want something triggered around your wake-up time:

# Morning briefing at 6:30 AM
30 6 * * * cd ~/clawd && openclaw run skills/morning-briefing/SKILL.md

If you're running the full Starter Pack, the Nightly Self-Improvement skill includes cron setup instructions. Follow them. The skill literally cannot work without the scheduler.

Problem 7: Permissions and File Access

Your agent might be running as a different user than the one who owns the skill files. Or the files might have restrictive permissions that prevent reading.

# Check permissions on your skills directory
ls -la ~/clawd/skills/

# Make sure everything is readable
chmod -R 644 ~/clawd/skills/*/SKILL.md
chmod -R 755 ~/clawd/skills/*/

Also verify that if your agent needs to write to skill-adjacent files (like the Access Inventory maintaining a tools table, or the Memory System updating knowledge graph files), those directories are writable:

# Ensure the agent can write to memory and data directories
chmod -R 755 ~/clawd/memory/
chmod -R 755 ~/clawd/data/

The Nuclear Option: Clean Reinstall of a Skill

If you've checked everything above and a specific skill still won't load, do a clean reinstall:

# Back up the old skill (just in case)
mv ~/clawd/skills/problem-skill ~/clawd/skills/problem-skill.bak

# Create fresh directory
mkdir -p ~/clawd/skills/problem-skill

# Re-download from Claw Mart and extract
# (use whatever download method you used originally)
cp ~/Downloads/problem-skill/SKILL.md ~/clawd/skills/problem-skill/

# Verify the file is readable and non-empty
wc -l ~/clawd/skills/problem-skill/SKILL.md
cat ~/clawd/skills/problem-skill/SKILL.md | head -20

# Update SOUL.md if needed
echo "- skills/problem-skill/ — [description]" >> ~/clawd/SOUL.md

Then start a fresh session. Don't try to fix it mid-conversation — skill loading happens at session initialization. A new session forces a clean read of all configuration files.

A Systematic Debugging Checklist

When a skill isn't loading, run through these in order. Stop at the first one that fails:

File exists? ls ~/clawd/skills/[skill-name]/SKILL.md
File named correctly? Must be exactly SKILL.md
File non-empty? wc -l ~/clawd/skills/[skill-name]/SKILL.md (should be >0)
File readable? cat ~/clawd/skills/[skill-name]/SKILL.md | head -5
Referenced in SOUL.md? grep "[skill-name]" ~/clawd/SOUL.md
No conflicting rules? grep -r "[relevant keyword]" ~/clawd/*.md ~/clawd/skills/*/SKILL.md
Context budget okay? Count total lines across all loaded files: cat ~/clawd/SOUL.md ~/clawd/AGENTS.md ~/clawd/skills/*/SKILL.md | wc -l
Fresh session? Start a new conversation after making changes
Cron set up? (For scheduled skills only) crontab -l | grep [skill-name]

Nine times out of ten, you'll find the issue at step 1, 2, or 5.

Setting Up Skills So They Never Break

The best debugging is the debugging you never have to do. Here's how I set up skills now to avoid all of the above:

Standardize your directory structure from day one. Every skill gets its own subdirectory under ~/clawd/skills/. Every skill file is named SKILL.md. No exceptions, no creativity with folder names.

Use a skills manifest. Keep a simple list in SOUL.md that maps skill directories to capabilities. Update it every time you add or remove a skill. This takes 30 seconds and prevents the "agent doesn't know it exists" problem permanently.

Start with a coherent skill set. This is genuinely why I recommend the Felix's OpenClaw Starter Pack for people getting started. The six skills in it — Three-Tier Memory, Coding Agent Loops, Email Fortress, Autonomy Ladder, Access Inventory, and Nightly Self-Improvement — are designed as a system. They share naming conventions, cross-reference each other correctly, and don't conflict. You skip the entire category of "skills fighting each other" problems. At $29 for six skills that actually work together out of the box, it's the fastest path to a functioning agent that doesn't need you to debug skill loading at 11 PM.

Test each skill immediately after install. Don't install five skills and then wonder which one broke. Install one, start a fresh session, explicitly ask your agent to use that skill, verify it works, then install the next one.

Next Steps

If you're currently staring at a skill that won't load, start with the debugging checklist above. Most issues resolve in under five minutes once you know where to look.

If you're setting up a fresh OpenClaw workspace and want to skip the configuration headaches entirely, grab the Starter Pack and follow the included README. It's the same skill set that runs real production agents — the installation path is well-worn.

And if you've found a loading issue that isn't covered here, that's genuinely useful information. Drop into the OpenClaw community and share what you hit. Every edge case that gets documented is one fewer person debugging at midnight when they should be shipping.