Skills are one of the fastest ways to make OpenClaw more useful. They are also one of the fastest ways to make your setup weird.

The first few installs feel like leverage. A week later, you can end up with skills scattered across directories, one agent seeing a different copy than another, repo-local behavior overriding host-level behavior, and nobody fully sure which installs are experiments versus actual policy.

This post is for that moment. Not just where to discover skills, but how to manage them: where they should live, when repo-local skills work, which copy wins, how to share them across multiple OpenClaw agents, and how to keep the whole thing from turning into a junk drawer.

The framing I find most useful is simple: treat skills like infrastructure, not bookmarks. Test them locally, promote them intentionally, and make sure your layout on disk matches the behavior you want across projects, hosts, and agents.

Where to look for skills

This part should stay small.

Good places to discover skills include:

  • ClawHub, for OpenClaw-native skills and plugins
  • skills.sh, for broader AgentSkills-compatible repos and packs
  • LarryBrain, for operator/agent patterns worth adapting
  • ShopClawMart, when creators package reusable higher-level workflows or paid assets

The important thing is not picking one universal marketplace. It is having a disciplined promotion process after discovery.

Discover widely, then get selective fast.

The real problem: host-machine entropy

Installing a skill is usually one command. Managing skills over time is harder because OpenClaw can load them from multiple places, and those places mean different things operationally.

Without a system, your host drifts into this:

  • old skills nobody remembers
  • local experiments accidentally treated as standard tooling
  • same-named skills overriding each other silently
  • one agent using a different setup than another
  • repo-local skills working in one project but not another

That is why the first job is not installation. It is deciding what each install location is for.

Where OpenClaw actually looks for skills

This is the part most people should understand earlier.

Per the official OpenClaw skills docs, these are the built-in skill roots, ordered by precedence from highest to lowest:

  1. <workspace>/skills
  2. <workspace>/.agents/skills
  3. ~/.agents/skills
  4. ~/.openclaw/skills
  5. bundled skills
  6. skills.load.extraDirs

That means the closest skill to the active workspace wins.

So yes, location matters a lot.

What each location is best for

<workspace>/skills

Best for:

  • project-specific behavior
  • repo-backed skills you want reviewed in Git
  • skills that should travel with that working repo/workspace

This is the highest-precedence path and usually the best place for approved project-level skills.

<workspace>/.agents/skills

Best for:

  • project-level agent skills that should apply inside the workspace before normal shared/personal copies
  • more structured per-workspace agent behavior

This is still workspace-scoped, but conceptually sits one layer more “agent-specific” than a plain skills/ folder.

~/.agents/skills

Best for:

  • personal agent-profile skills shared across workspaces on one machine
  • your own reusable patterns that are not yet team policy

Useful, but easy to forget if you rely on it too heavily.

~/.openclaw/skills

Best for:

  • host-level shared skills available to all agents on the same machine
  • managed overrides that should beat bundled skills without dirtying the repo

This is a strong place for shared host behavior, but it is not automatically the right place for multi-host distribution.

skills.load.extraDirs

Best for:

  • deliberately configured shared packs
  • low-precedence common skill directories

Useful, but intentionally low precedence.

So, will repo-local skills work?

Yes, absolutely, if they are in the right place.

If OpenClaw is working inside a repo or workspace, and that repo contains:

  • <workspace>/skills/...
  • or <workspace>/.agents/skills/...

then OpenClaw can load and use those skills.

If the repo just contains some random folder called my-skills/ or docs/skills/ or anything outside those recognized roots, OpenClaw will not automatically leverage it unless:

  • you move it into one of the recognized skill roots, or
  • you explicitly add that folder through skills.load.extraDirs

This is the clean mental model:

Repo-local skills work when they are OpenClaw-visible, not merely when they exist somewhere in the repo.

That distinction matters.

Repo-local skills vs host-level skills

Here is the practical difference.

Repo-local skills are best when

  • the behavior is specific to one project
  • you want the skill versioned next to the codebase
  • you want it to be easy for collaborators or agents working in that repo to inherit it
  • you want the repo copy to override more general shared copies

Host-level skills are best when

  • the skill is useful across many projects
  • you want a common baseline on one machine
  • you are overriding bundled skills locally without editing the repo
  • the behavior belongs to the host setup, not one project

If you blur these two categories, things get messy quickly.

Skill location and skill visibility are not the same thing

This is another subtle but important point from the docs.

  • Location determines which copy wins.
  • Visibility determines which agents can actually use that visible skill.

So even if a skill exists in a shared location, you can still restrict who gets it via agent skill allowlists.

This is useful when:

  • a skill should live on the host, but only certain agents should use it
  • you want a common pool without making every skill universally visible
  • you want tighter operational boundaries across agents

That is why “where did I install it?” and “which agents should have it?” are two separate decisions.

The host-machine policy I recommend

If I were setting this up from scratch, I would use this rule set.

Rule 1: default to repo-backed for anything important

If a skill affects repeated workflows or output quality in a meaningful way, put it where it can be reviewed and synced.

Rule 2: keep experiments clearly separate

Do not blur:

  • “I am testing this locally”
  • with
  • “this is now part of our real operating environment”

Rule 3: make one path authoritative

Your team should know which path wins as policy.

For example:

  • repo-backed workspace skills are authoritative for project behavior
  • host-level shared skills are for common baseline behavior
  • machine-local extras are non-authoritative experiments

Rule 4: sync on purpose, not by accident

If multiple agents matter, do not rely on memory or manual installs. Use a real distribution path.

Rule 5: review skill additions like infra changes

A skill can materially change behavior. Treat it with the seriousness of a config change.

The lifecycle every skill should go through

Stage 1: discover

Find candidate skills from the places above.

Stage 2: test

Try them locally first.

Questions worth asking:

  • Does it actually improve output quality?
  • Does it reduce prompt bloat or retries?
  • Does it assume a CLI, env var, or config state that other agents do not have?
  • Does it include scripts or executable helpers that raise the risk profile?

Stage 3: approve or reject

Every skill should eventually become one of:

  • rejected and removed
  • kept local for one-machine use
  • promoted into the reviewed/shared path

Stage 4: distribute

If approved, move it into the path your real sync/distribution flow manages.

Stage 5: prune

Unused, duplicate, or confusing skills should be removed. Skill rot is real.

How to inspect a skill before you trust it

Read SKILL.md

Check:

  • what problem it claims to solve
  • whether the instructions are coherent
  • whether the description honestly matches the behavior
  • whether it is focused or sprawling

Inspect scripts and bundled files

A pure instruction skill is one thing. A skill with executable helpers is a different risk class.

Check runtime assumptions

Look for:

  • required binaries
  • required env vars
  • config assumptions
  • sandbox or container mismatches

Test on a real task

Do not judge a skill by the README. Judge it by whether it helps real work.

How to share skills across separate OpenClaw agents

This is where most operators eventually end up.

The right answer depends on whether your agents share the same host or live as separate instances.

Option 1: same host, shared local skills

If multiple agents run on the same machine, shared host-level locations can work well:

  • ~/.openclaw/skills
  • skills.load.extraDirs

This is a reasonable common baseline when the agents really do share one host.

The downside is that these paths can become invisible infrastructure unless you document and manage them carefully.

Option 2: separate agents, repo-backed sync

If your agents are separate OpenClaw instances, separate containers, or separate hosts, repo-backed sync is usually the cleanest answer.

Why this pattern works:

  • one source of truth
  • reviewable diffs
  • predictable rollout
  • less dependence on remembering what was manually installed where

How we do it

In our setup, approved skills live in the agent-control-plane-config repo. Then each agent pulls from that repo on a schedule.

That means:

  • skills are reviewed in Git first
  • the repo becomes the authoritative shared set
  • scheduled pull sync keeps Greg and the separate OpenClaw agents aligned
  • local-only experiments stay local until intentionally promoted

I trust this pattern more than ad hoc copying because it solves the governance problem, not just the file-copy problem.

A simple sharing policy that works

For multiple separate agents, use this split:

  • shared repo + scheduled sync for approved team skills
  • local host installs for experiments
  • explicit promotion step when a local skill proves useful

That keeps agents aligned without killing experimentation.

Common failure modes

  • A skill exists on one host but never made it into the shared distribution path.
  • A repo-local skill overrides a host-level skill and nobody notices.
  • A machine-wide skill becomes a hidden dependency.
  • A sync process overwrites local customizations without a clear policy.
  • The team never decided which path is authoritative.

Most of these are not discovery problems. They are governance problems.

A lightweight checklist you can actually use

Before installing

  • What workflow problem is this skill supposed to improve?
  • Is this experimental or something I expect to standardize?
  • Where will it live?

Before approving

  • Did I read SKILL.md?
  • Did I inspect scripts and helper files?
  • Did I verify required binaries, env vars, and config assumptions?
  • Did it help on a real task?

Before distributing

  • Is the approved copy repo-backed or otherwise intentionally managed?
  • Is the sync path explicit?
  • Will every relevant agent get the same version?
  • Do we know which installs are authoritative and which are experimental?

During cleanup

  • Is this still used?
  • Is it duplicated elsewhere?
  • Is it causing overrides or confusion?
  • Can I remove it safely?

Practical takeaway

The best OpenClaw skill setup is not the one with the biggest collection. It is the one where the host machine stays understandable and multi-agent behavior stays predictable.

Use the host to evaluate. Use repo-backed paths to standardize. Understand where OpenClaw actually looks. Know which copy wins. Use sync to distribute. Use pruning to stay clean.

That is how you get the upside of skills without turning your OpenClaw into a junk drawer.