OpenClaw Skills Precedence Guide: How Skill Loading Really Works

If you want the short answer, OpenClaw skill precedence decides which copy of a skill wins when the same skill name exists in more than one location.

That sounds like a niche detail until a team starts using shared skills, project-specific skills, and agent-specific overrides at the same time.

Then it becomes one of the most important setup details in the whole system.

OpenClaw gives you several places to load skills from. That is powerful, but it also means you need a clear mental model. Otherwise you end up wondering why a skill behaves differently in one workspace than another or why a local override is not being picked up the way you expected.

This guide walks through how skill loading works in OpenClaw, what the precedence order is, how allowlists fit in, and how to avoid the most common mistakes.

What are OpenClaw skills?

According to the docs, OpenClaw uses AgentSkills-compatible skill folders to teach the agent how to use tools and perform repeatable work. Each skill lives in a directory with a SKILL.md file and instructions.

That matters because skills are one of the cleanest ways to make repeated agent behavior more consistent.

Where OpenClaw loads skills from

The docs describe six sources for skill loading:

1. extra skill folders from skills.load.extraDirs
2. bundled skills
3. managed or local skills in ~/.openclaw/skills
4. personal agent skills in ~/.agents/skills
5. project agent skills in <workspace>/.agents/skills
6. workspace skills in <workspace>/skills

That list matters because it explains why the same skill name can behave differently across machines or projects.

The actual precedence order

If a skill name conflicts, OpenClaw resolves it with a very specific precedence chain.

<workspace>/skills wins first. Then <workspace>/.agents/skills. Then ~/.agents/skills. Then ~/.openclaw/skills. Then bundled skills. Then extra skill directories.

This is the part people need to remember. Closest to the current workspace wins.

That is a sane model because the most local version is usually the one with the most relevant context. But it also means local overrides can quietly replace a shared skill if you are not paying attention.

Shared skills versus per-agent skills

This is where teams often get turned around.

A shared skill can be visible to many agents on the same machine. A workspace skill belongs to one workspace. A project agent skill sits in between and applies to that workspace before the normal workspace skills/ folder. Personal agent skills apply across workspaces for that user.

Once you understand those layers, debugging gets much easier.

Skill visibility is not the same as skill precedence

This is a subtle but important distinction in the docs.

Skill location decides which copy of a skill wins when names conflict. Skill allowlists decide which visible skills an agent can actually use.

Those are different controls.

That means you can have a skill that exists and even wins the precedence battle, but an agent still may not be allowed to use it if the allowlist blocks it.

How agent skill allowlists work

The docs describe agents.defaults.skills as a shared baseline. Then agents.list[].skills can override that per agent.

A missing per-agent skill list means the agent inherits the default. An empty list means no skills. A non-empty list becomes the final set for that agent and does not merge with defaults.

That last rule matters a lot. Teams sometimes expect the lists to merge. They do not.

Why teams get confused about skills

Most skill confusion comes from one of four things:

• the same skill name exists in more than one place
• someone assumes visibility equals permission
• a local override is winning quietly
• a per-agent allowlist replaces defaults instead of extending them

Once you know those patterns, troubleshooting is much faster.

A practical operating model

If you want skills to stay understandable, use this approach:

• keep shared baseline skills in a shared location
• use workspace overrides only when the project truly needs them
• keep skill names predictable
• document agent allowlists clearly
• treat third-party skills as untrusted until reviewed

The docs are explicit on that last point. Third-party skills should be treated as untrusted code.

Internal links worth reading next

• Skills guide
• Workspace files
• How to add and use skills in OpenClaw
• Improve agent productivity with better workspace rules and skills

Official references:

• OpenClaw skills docs
• OpenClaw docs index
• OpenClaw on GitHub

Final take

If you understand OpenClaw skill precedence, you stop guessing why agent behavior changed. You can see which skill won, why it won, and whether the agent was even allowed to use it.

FAQ

What is OpenClaw skill precedence?

It is the order OpenClaw uses to decide which copy of a skill wins when the same skill name exists in multiple locations.

Which skill location has highest priority?

The workspace skills/ folder has the highest precedence.

Do agent skill allowlists merge with defaults?

No. A non-empty per-agent skill list becomes the final set for that agent.

Are shared skills the same as workspace skills?

No. Shared skills can be visible across agents, while workspace skills are local to one workspace.

Should I trust third-party skills automatically?

No. The docs advise treating them as untrusted code and reviewing them before enabling.

Why precedence matters in real projects

Precedence sounds abstract until you are working in a real team.

One person installs a shared skill globally. Another creates a project override. A third person assumes the agent is still using the shared copy. Suddenly the behavior changes, and nobody is sure why.

That is a precedence problem, not a model problem.

A practical example

Say your team has a shared github skill in a shared location, but one project needs a stricter version with custom instructions. If that project adds a workspace copy under skills/, the workspace version wins.

That is probably what you wanted, but only if everyone knows it happened.

Why allowlists deserve separate attention

The docs are helpful here because they separate visibility from permission.

A skill may be visible in the system and still unavailable to a given agent. That means a debugging pass needs two questions, not one:

• which copy of the skill won?
• was the agent allowed to use it?

Skipping the second question leads to a lot of unnecessary confusion.

Security and trust are part of the story

The skill docs also make a broader point: third-party skills should be treated as untrusted code.

That is not paranoia. It is good operational hygiene. Skills can shape how tools get used, what instructions are applied, and how risky actions are framed. Teams should review outside skills before enabling them, especially in environments with external tools or sensitive data.

One clean operating pattern

A simple pattern that works well is to keep baseline shared skills minimal, use workspace overrides only for clear project reasons, and avoid duplicate names unless the override is intentional. That keeps the precedence model easier to explain and much easier to debug.

How to troubleshoot a weird skill result

If a skill behaves differently than expected, start with the basics.

Check whether the same skill name exists in more than one location. Check which location should win based on precedence. Then check whether the agent allowlist permits that skill at all. Those three checks solve a surprising amount of confusion.

In other words, do not treat skill behavior as mysterious until you have ruled out the loading model.

Why this matters for multi-agent setups

In multi-agent environments, the same team may use shared skills, agent-specific rules, and workspace-specific overrides all at once. That makes precedence even more important. If you do not understand which layer wins, you will misread agent behavior and waste time debugging the wrong thing.

The simplest mental model

Think local first. The closer a skill is to the active workspace, the more likely it is to win. Then ask whether the agent is actually allowed to use it.

That mental model is not the whole docs page, but it is the part most people need day to day.

Reliable skill behavior starts there.

Good skill hygiene saves real debugging time.

That is a small detail with big practical payoff.

One last practical takeaway

When a skill surprises you, check the winning location before you blame the agent. A lot of strange behavior turns out to be a very ordinary precedence issue.

That makes this topic more operational than theoretical.

Understanding the loading model pays off immediately.

That alone prevents a lot of avoidable confusion.

Clearer systems are easier to trust.

That makes day-to-day setup much less mysterious.