OpenClaw skills

A skill is a folder with a markdown file in it. That file tells the agent how and when to reach for a tool, and OpenClaw decides which of those files an agent can see before the model ever gets a turn. The rules are worth knowing because they explain both the surprises (a skill that will not appear) and the costs (every eligible skill spends prompt tokens). Here is the whole mechanism.

Where skills come from

• File-backed skills load highest precedence first: workspace skills, project agent skills, personal agent skills in the home directory, managed skills in the state directory, workshop skills for that agent, bundled skills shipped with the install together with the Custodian library, and finally extra directories and plugin skills; when the same name appears twice, the highest source wins.
• Roots support grouped layouts, so a skill file found anywhere under a configured root up to six levels deep is discovered, and finding one ends traversal below that directory; the folder path is organisation only, because the name and slash command come from the name field in the frontmatter or the directory name when it is missing.
• A connected headless node can publish the skills installed in its own skills directory: they appear in the agent list while the node is connected and vanish when it disconnects, a local or gateway skill keeps its name on a collision while the node skill gets a node-prefixed one, and because its files and binaries live on the node you run it with the exec tool targeting that node.
• Visibility follows the path: workspace skills are visible to one agent, project skills to that workspace's agent, personal skills to agents on the default state, managed skills to every agent sharing that state, workshop skills to the agent that drafted them, and extra directories to every agent sharing that config; a workshop skill learned by one agent is not shared with another until it is published to the managed library.

Treat third-party skills as untrusted code. Read them before enabling.

Allowlists, gating and the personal library

Location and visibility are separate controls. An allowlist under the agent defaults sets a shared baseline, a non-empty per-agent list is the final set and does not merge with the defaults, an empty array exposes no skills at all, and the effective list applies to prompt building, slash-command discovery, sandbox sync and snapshots alike. Gating is the other filter: a metadata block in the frontmatter can require binaries on the path, at least one of a set, environment variables, truthy config paths or a specific operating system, and the always flag bypasses everything except the platform filter. On a shared gateway, identified operators keep a personal library instead of editing everyone's workspace: saving publishes a complete immutable revision whose hash covers file paths, content, sizes and executable flags, a session keeps the revisions it selected until someone explicitly attaches or refreshes, and a new session selects up to 64 enabled library skills with personal ones first.

Installing, overriding, refreshing

• The skills commands install from the public registry into the workspace by default or into the shared directory with the global flag, and can install from a git repository or a local directory; verification asks the registry for the skill's trust envelope and exits non-zero when the registry marks it failed, while an operator install policy command can gate every install path and fails closed when it cannot return a valid decision.
• Config entries toggle and configure skills: enabled false disables a skill even when bundled, an api key field backs the primary environment variable a skill declares, an env map is injected only when the variable is not already set, a config bag holds custom fields, and a bundled allowlist narrows bundled skills only; keys match the skill name unless the skill declares its own key.
• Eligible skills are snapshotted when a session starts and reused until a refresh trigger fires: the watcher sees a skill file change, the gateway restarts, a new eligible remote node connects, or native watch capacity runs out and the next turn starts; the refreshed list is picked up on the next agent turn, and a changed allowlist also forces a refresh.

OpenClaw skills configuration is the full configuration schema for these keys and The OpenClaw exec tool the tool most skills end up calling.

What skills cost

When at least one skill is eligible, OpenClaw injects a compact block into the system prompt: a fixed intro plus roughly 97 characters per skill on top of the name, description and location lengths, which at about four characters per token is around 24 tokens per skill before those fields. If the rendered block would exceed the configured prompt budget, OpenClaw first preserves as many skill identities as the description-free format allows, then spends what remains on shortened descriptions, and notes that a check command exists. Short, specific descriptions are the cheapest way to keep a large catalog affordable. Two security boundaries matter as much as the cost: environment injection is scoped to the host agent run and has no effect inside a sandbox, and skill allowlists are not a shell authorization boundary, so an agent that can also run commands needs OpenClaw sandboxing explained and OpenClaw exec approvals constraining that shell separately.

On Diali

On Diali the runtime configuration is generated from the dashboard and replaced at each release, and the workspace files that carry skills live on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). Hosted OpenClaw on Diali describes the hosted assistant and Diali pricing the plans it ships in.

• Seven sources, highest wins; the name comes from the frontmatter.
• Gating filters at load time; allowlists filter per agent.
• About 24 tokens per eligible skill before name and description.