OpenClaw skills: choose per-agent, shared, or workspace scope
OpenClaw skills should live at the narrowest scope that still fits the job. Put a client-specific workflow in that agent’s workspace; put a genuinely reusable local capability in a shared directory; use an allowlist when a capable skill should not be visible to every agent. The choice matters because skill location determines both which copy wins on a name collision and who can inherit it.
That is a more useful question than “where do I install this?” A skill that drafts newsletters for one brand should not silently become available to a finance agent. Conversely, duplicating the same calendar skill into five workspaces creates five update paths and five chances for drift.
Contents
- The short version
- How OpenClaw skills load
- Choose a scope by ownership
- Use precedence for local exceptions
- Keep visibility separate from execution permissions
- A practical layout for a small agent team
- FAQ
The short version
OpenClaw discovers skills through configured directories. A skill is a directory containing a SKILL.md file, and the name in its frontmatter identifies it. When more than one copy uses the same name, OpenClaw keeps the highest-precedence copy.
| If the skill is for… | Start here | Why |
|---|---|---|
| One agent’s recurring task | <workspace>/skills | It stays with that agent’s work and overrides broader copies when needed. |
| A project-specific convention | <workspace>/.agents/skills | It belongs to that workspace without becoming machine-wide. |
| A personal capability used by every local agent | ~/.agents/skills | One maintained copy is available across that user’s agents. |
| A managed local baseline | ~/.openclaw/skills | It is shared across local agents and can be updated centrally. |
| A deliberately external skill library | skills.load.extraDirs | It keeps a separate repository or shared source in one place. |
This is a placement decision, not a security decision by itself. If an agent must not see a skill, configure its skills allowlist. If an agent must not execute a shell command, reach a network endpoint, or read a credential, control those permissions separately.
For the surrounding model, read how OpenClaw works. The Gateway is the control plane; a skill is instruction and supporting material the agent can load, not a separate sandbox or user account.
How OpenClaw skills load
OpenClaw documents six loading layers. Workspace skills have the highest priority, followed by project-agent and personal-agent locations. Managed local skills, bundled skills, and extra directories are lower priority.
| Priority | Source | Typical use |
|---|---|---|
| Highest | <workspace>/skills | An override or a workflow owned by one agent |
| 2 | <workspace>/.agents/skills | Project-specific guidance |
| 3 | ~/.agents/skills | Personal defaults across local agents |
| 4 | ~/.openclaw/skills | Shared managed skills |
| 5 | Bundled skills | Capabilities supplied with OpenClaw |
| Lowest | skills.load.extraDirs and plugin skills | An external library or plugin-provided guidance |
The important behavior is simple: a matching skill name at a higher layer wins. Folder names help humans organize files, but they do not make a new skill identity. OpenClaw uses the frontmatter name when it is valid, falling back to the directory name only when it is absent.
That means a local research skill can intentionally replace a bundled research skill. It also means two unrelated directories that both declare name: research are a collision waiting to happen. Treat skill names like stable interfaces: use a clear namespace when the capability is specific, such as acme-content-review, instead of taking a generic name by accident.
If you are writing the first custom workflow, start with how to create a custom OpenClaw skill. Keep the skill small enough to review. A good skill tells an agent when to use a workflow, what tools or files it needs, and where the boundaries are.
Choose a scope by ownership
Scope should follow the owner of the workflow and the cost of a mistake.
Put client or role-specific skills in the workspace
A workspace skill is the best default for instructions that depend on one agent’s goals, files, tone, or approved tools. A sales-research agent may need a prospecting rubric that makes no sense for a support agent. Keeping it in <workspace>/skills makes the association obvious and lets the agent’s workspace override a shared generic version.
This is also the right place for a safe local modification. Suppose every agent has a shared web-research skill, but one regulated project needs extra citation checks. Keep the shared version intact and add a workspace-level version with the same skill name only when the override is deliberate and documented. Otherwise, use a new name so an operator can see both capabilities in the skill list.
Put shared operating procedures in a managed directory
Use ~/.openclaw/skills for routines that should behave the same way for every local agent: an approved incident template, a release checklist, or a company-wide data-handling procedure. This creates one update location, which is valuable when the procedure changes.
Shared does not mean universal. An allowlist can still narrow a specialized workflow, such as a production deployment guide, to the release agent.
Use extra directories for a maintained library
Use skills.load.extraDirs for a separately maintained library. It remains low precedence, and the OpenClaw skills security checklist is a sensible baseline before adding a shared third-party workflow.
Use precedence for local exceptions
Precedence is most useful when it expresses an intentional policy, not when it hides a surprise. Before overriding a skill, answer these questions:
- Does the local agent truly need different instructions, or should the shared skill be improved for everyone?
- Will another operator recognize the duplicate name and understand why it wins?
- Does the override inherit a dependency, credential, or tool assumption that only exists in one workspace?
- Is there a test task that proves the intended skill loaded?
A healthy pattern is a stable shared skill plus a narrow workspace variant with a documented reason. Several independently edited copies of the same name make debugging painful because the file you inspect may not be the one that loaded.
Use openclaw skills check when skill descriptions are compacted or the list is truncated for prompt budget. Test a harmless task before relying on a changed skill in production.
Keep visibility separate from execution permissions
An agent’s skills allowlist controls what skills are available in its prompt, slash-command discovery, sandbox sync, and skill snapshots. It does not make the host safe by itself.
For example, a deployment skill may describe a release command. Removing that skill from an agent’s allowlist prevents the agent from receiving those instructions through the skill system. It does not remove an already available exec capability, network access, credentials, or operating-system permissions. Those require their own controls: sandboxing, OS-user separation, command allowlists, and narrowly scoped credentials.
The distinction is worth preserving because it avoids false confidence. Use a skill allowlist to manage context and workflow exposure. Use tool policy and infrastructure boundaries to manage what the agent can actually do.
For a shared ClawHub install, prefer an owner-qualified reference such as @owner/skill, verify it before installation, and use the install scope intentionally. The documented --global install path targets shared managed skills; the default path targets the active workspace.
A practical layout for a small agent team
A three-agent setup might look like this:
~/.openclaw/skills/
incident-update/
source-citations/
~/agents/
writer/
skills/
brand-voice/
client-a-fact-check/
operator/
skills/
deploy-production/
researcher/
skills/
competitor-scan/The shared directory contains small baseline skills that every agent may use. The writer gets brand and client checks that should not leak into the operator’s context. The operator’s deployment instructions stay close to the workspace and can be allowlisted to that agent alone.
This arrangement also makes review cheaper. A change to source-citations has one owner and one diff. A change to client-a-fact-check affects one workspace. If a new tool requires a secret, do not put that secret in a skill body. OpenClaw documents skill environment injection as host-process-only for the agent turn, not sandbox injection; that is a reason to keep secrets out of prompts and logs and to use the narrowest possible configuration.
Move a workflow from a workspace into the shared layer only when it has stable ownership and a review path.
FAQ
Should all OpenClaw skills be installed globally?
No. Global installation makes a skill visible from the shared managed directory to all local agents unless allowlists narrow it. Use the default workspace installation for an agent-specific workflow, and use --global only when a centrally maintained shared copy is the intended design.
What happens when two skills have the same name?
The skill from the higher-precedence source wins. Workspace skills outrank project-agent, personal-agent, managed, bundled, and extra-directory skills. Avoid accidental collisions by using explicit names for specialized workflows.
Are skills allowlists a security boundary?
They control skill visibility, not host authority. A restrictive allowlist is useful for reducing workflow exposure, but shell access, network access, sandboxing, and credentials need separate controls.
Can I use a Git repository as a skill source?
Yes. OpenClaw documents Git installs through openclaw skills install git:owner/repo@ref. Git and local sources need a SKILL.md at the source root. Reinstall Git or local sources to refresh them; the standard update command tracks ClawHub installs.