How I Organized 100+ OpenClaw Skills Across 5 Directories (And What Finally Worked)

TL;DR: Put ClawHub installs in workspace/skills/. Use symlinks from ~/.agents/skills/ to ~/.openclaw/skills/ to enable skills from other sources on demand. Avoid extraDirs — it's the lowest priority and removes your ability to filter. Keep a plain-text registry so nothing gets lost between sessions.

I run OpenClaw as my daily AI assistant — it handles everything from drafting documents to deploying apps. Over six months, I'd installed skills from ClawHub, skills.sh, GitHub repos, and built plenty of my own. One morning I counted: 102 skills spread across 5 directories, with duplicates everywhere. The same skill sometimes appeared three or four times.

If you're trying to manage AI agent skills at any kind of scale, this problem will find you. Here's the story of how I went from chaos to a clean, maintainable OpenClaw skills management system — and the detours I took along the way.

The OpenClaw Skills Mess: 5 Directories, No Plan

Here's what my setup looked like before I fixed it:

Directory	Count	Source	Scanned by OpenClaw?
`/opt/homebrew/.../openclaw/skills/`	52	Built-in (npm)	✅ Lowest priority
`~/.openclaw/workspace/skills/`	19	ClawHub + hand-built	✅ Highest priority
`~/.openclaw/skills/`	27 (20 were symlinks)	Manual + symlinks	✅ High priority
`~/.agents/skills/`	20	skills.sh installs	❌ Not scanned
`~/.claude/skills/`	20	Claude Code only	❌ Not scanned

After deduplication, I had about 50 custom skills and 52 built-in ones. But because things were scattered, my agent couldn't find half of them. Skills I'd spent hours building would vanish between sessions because they lived in directories OpenClaw never looked at.

If you're running OpenClaw in production — whether on a Mac Studio in Sydney or a VPS in Auckland — this problem scales faster than you'd expect.

How OpenClaw Actually Loads Skills

Before diving into solutions, it helps to understand the loading order. According to the official docs, same-name skills at a higher priority level override lower ones:

workspace/skills/ — highest priority (your current project)
~/.openclaw/skills/ — user-level
Built-in skills — shipped with the npm package
skills.load.extraDirs — any extra directories you configure (lowest priority)

This is a sensible design. My mistake was fighting it instead of working with it.

What Didn't Work: Common OpenClaw Skills Management Mistakes

Mistake 1: "Just Put Everything in One Directory"

My first instinct was to copy every skill into ~/.openclaw/skills/. Simple, right?

Wrong. Different installation tools write to different directories by design. ClawHub installs to workspace/skills/. skills.sh installs to ~/.agents/skills/. Force-merging them means abandoning the tools that installed them — no more one-click updates, no lockfiles, no provenance tracking.

I tried it for a day. Updating a single skill meant manually copying files around. I reverted.

Mistake 2: The `extraDirs` Trap

OpenClaw lets you add extra scan directories via skills.load.extraDirs in your config. I added ~/.agents/skills/ so OpenClaw would scan everything skills.sh had installed.

This seemed perfect. One config line and 20 more skills appeared instantly.

The problems emerged quickly:

No filtering. Every skill in that directory became visible to the agent, whether I wanted it or not. Experimental, broken, or irrelevant skills all showed up in the agent's context.
Duplicate loading. Skills I'd already symlinked to ~/.openclaw/skills/ were now loaded twice — once via the symlink, once via extraDirs.
Context bloat. More skills in the scan = more descriptions injected into every prompt = more tokens burned = higher latency and cost.
Lowest priority. extraDirs sits at the bottom of the priority chain, so you can't use it to override anything — it's purely additive.

I removed extraDirs within a week. Installed ≠ enabled — and extraDirs erases that distinction.

Mistake 3: Building Skills Without Registering Them

This was the most painful mistake. I'd build a useful skill, test it, confirm it worked — and then move on to the next task. Two weeks later, I'd forget it existed. My agent certainly didn't remember; AI agents have no memory continuity across sessions.

I rebuilt at least three skills from scratch before I realised the pattern: if you don't register it, it doesn't exist.

(I also lost time debugging a custom config wrapper that broke on edge cases. Lesson: use native tools like gateway config.patch for config changes — custom wrappers add maintenance burden and break at the worst times.)

The Solution: Warehouse-and-Shelf Pattern for OpenClaw Skills

After all those detours, I landed on a model I call "Warehouse and Shelf":

~/.agents/skills/          ← WAREHOUSE (skills.sh installs land here)
       ↓ symlink (enable on demand)
~/.openclaw/skills/        ← SHELF (OpenClaw scans this — symlink = enabled)
workspace/skills/          ← WORKBENCH (self-built + ClawHub, highest priority)
built-in skills            ← npm-managed, don't touch

A symlink (short for "symbolic link") is like a shortcut or alias — it makes a file or folder appear in a new location without actually copying it. If you're on macOS or Linux, you've probably used ln -s before; on Windows, mklink does the same thing.

How It Works in Practice

Installing a new skill from skills.sh:

# skills.sh installs to ~/.agents/skills/my-new-skill/
# Then I decide whether to enable it:
ln -s ~/.agents/skills/my-new-skill ~/.openclaw/skills/my-new-skill

Installing from ClawHub:

clawhub install some-skill
# Automatically goes to workspace/skills/ — already visible, nothing else needed

Building my own: Drop it in workspace/skills/ with a SKILL.md. Done.

Disabling a skill:

rm ~/.openclaw/skills/my-new-skill  # just removes the symlink, not the skill

The config is dead simple:

{
  "skills": {
    "load": {
      "extraDirs": []
    }
  }
}

No extraDirs. No magic. Every enabled skill is an explicit symlink or a file in a scanned directory.

The Registry: If You Build It, Write It Down

I created a SKILLS_REGISTRY.md — a plain markdown table listing every custom skill, its location, source, and status. The rule is simple and absolute:

If you create or install a skill, add a line to the registry. No exceptions.

I also added this to my AGENTS_RULES.md as a trigger-based rule, so the agent enforces it automatically. No more phantom skills.

What I Learned About Organizing OpenClaw Skills

1. Installed ≠ Enabled. This is the core insight. The warehouse/shelf separation means you can experiment freely without polluting your agent's context.

2. extraDirs is a trap. It looks like a shortcut but costs you control. It's also the lowest priority in the loading chain. Symlinks give you per-skill granularity.

3. Don't fight the priority system. OpenClaw's workspace > user > built-in hierarchy is well-designed. Work with it.

4. Register everything. AI agents have no cross-session memory. An unregistered skill is a skill that will be rebuilt from scratch in three weeks.

5. Use native tools for config. Custom wrappers break. gateway config.patch doesn't.

6. The industry hasn't solved this yet. As of March 2026, ClawHub is the largest skill marketplace (over 4,000 GitHub stars) but the ecosystem is still early. Most people manage 5–10 skills by hand. If you have 50+, you need a system.

7. Audit your self-built tools regularly. APIs change, subscription models shift, and that clever usage-tracking skill you built six months ago might be silently broken. I deleted three tools in this cleanup because their underlying APIs had changed.

FAQ

Q: Where should I put my OpenClaw skills?

Three places: workspace/skills/ (highest priority — for ClawHub installs and self-built skills), ~/.openclaw/skills/ (user-level — use symlinks to enable skills from other sources), and built-in skills (managed by npm, leave them alone).

Q: I installed a skill with skills.sh but OpenClaw can't find it. Why?

skills.sh installs to ~/.agents/skills/, which OpenClaw doesn't scan by default. Create a symlink: ln -s ~/.agents/skills/the-skill ~/.openclaw/skills/the-skill.

Q: Should I use extraDirs or symlinks?

Symlinks. extraDirs exposes an entire directory with no filtering, and it's the lowest priority in the loading order. Symlinks let you enable or disable individual skills. You'll thank yourself when you have 30+ skills installed but only want 15 active.

Q: My agent keeps rebuilding skills I already made. How do I stop this?

Create a registry file (e.g., SKILLS_REGISTRY.md) and add a rule to your AGENTS_RULES.md that the agent must check the registry before building anything new, and must register anything it creates.

Q: How do I track my Claude Max/Pro subscription quota?

During this cleanup I ran into this exact problem — I wanted to know how much quota I had left, not how much I'd spent. I ended up building a skill called claude-quota-checker that automates Claude Code CLI's /usage command via tmux. It shows remaining %, plan type, and reset times in about 8 seconds, no API keys needed. clawhub install claude-quota-checker if you're curious.

Q: What's the best skill marketplace for OpenClaw?

As of early 2026, ClawHub is the clear leader. We evaluated Paks (41 stars), askill (6 stars), Tessl (commercial), and others — none are mature enough for production use yet.

Q: Does this approach work on Linux / cloud servers?

Yes. The symlink pattern is OS-agnostic. I run this on a Mac Studio (macOS) but the same structure works on any Linux VPS or CI environment. Just adjust the homebrew path for built-in skills.

Wrapping Up

Managing OpenClaw skills at scale is a solved problem — you just have to solve it yourself, because the tooling isn't there yet. The warehouse-and-shelf pattern with symlinks has been running cleanly for me since I set it up, and the registry rule means nothing gets lost between sessions.

If you're just getting started with OpenClaw, set up this structure before you hit 20 skills. Future you will be grateful.