OpenClaw skills: load order, ClawHub and writing your own

Updated October 1, 2026 · 9 min read

OpenClaw skills are folders with a SKILL.md file that teach the agent how and when to use its tools. OpenClaw loads them from seven precedence tiers, with your workspace first, and you install community skills from ClawHub with openclaw skills install. Treat every third-party skill as untrusted code: read it and check its ClawHub audit before you enable it.

We have not installed OpenClaw for this guide. The commands and paths below come from docs.openclaw.ai and ClawHub’s docs as of October 2026. We do run Hermes Agent skills, which use the same SKILL.md format, across several profiles on one Mac, and compare the two near the end.

What are OpenClaw skills?

A skill is a directory with a SKILL.md at its root: YAML frontmatter, then markdown instructions. OpenClaw follows the AgentSkills spec. Only two fields are required, name and description:

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

When the user asks to generate an image, use the `image_generate` tool...

The folder can also hold scripts, references and assets. Use {baseDir} in the body to point at them without hardcoding a path, for example {baseDir}/scripts/run.sh.

Optional frontmatter keys from the docs:

• user-invocable (default true): expose the skill as a slash command.
• disable-model-invocation (default false): keep it out of the model’s prompt, so it only runs when you call it.
• command-dispatch: tool with command-tool: send the slash command straight to a tool, skipping the model.
• homepage: a URL shown in the macOS Skills UI.

You call a skill with /name in chat, or by typing $ in the Control UI composer and picking it. One message can reference up to eight skills, as in Use $github and $release_notes to summarize this change.

Where do OpenClaw skills load from?

From these places, highest precedence first. When two skills share a name, the higher one wins:

Three details the docs spell out:

• Grouping is free. OpenClaw finds a SKILL.md anywhere up to six levels under a root, so skills/personal/research/SKILL.md is still the skill research. The name and slash command come from the name field, not the folder.
• Collisions are logged. A workspace skill that overrides a bundled one shows as a warning in the discovery summary.
• Codex skills are not read. $CODEX_HOME/skills is not a skill root. openclaw migrate plan codex lists those skills and openclaw migrate codex copies them in.

OpenClaw snapshots the eligible skills when a session starts. A watcher refreshes the list when a SKILL.md changes, and the next turn picks it up. If watching is off, start a new session with /new or run openclaw gateway restart.

Which agents see which skills?

In a multi-agent setup, each agent has its own workspace, so the path decides visibility. <workspace>/skills and Workshop skills belong to one agent. <state-dir>/skills and extraDirs reach every agent using that state or config.

To narrow it further, set allowlists in openclaw.json. A non-empty list for an agent replaces the defaults; an empty list hides every skill:

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    entries: {
      writer: { default: true },          // inherits github, weather
      docs: { skills: ["docs-search"] },  // replaces the defaults
      "locked-down": { skills: [] },      // no skills
    },
  },
}

Skills can also gate themselves with metadata.openclaw.requires: binaries on PATH (bins, anyBins), environment variables (env), truthy config paths (config) or an os list. A skill whose requirements fail stays installed but is not offered. When a skill does not show up, run:

openclaw skills list --eligible
openclaw skills check
openclaw skills info <name>

The docs warn that an allowlist is not a shell boundary. If the agent can use exec, sandbox it separately.

How do I install OpenClaw skills from ClawHub?

ClawHub is the public registry for OpenClaw skills and plugins. The openclaw CLI searches, installs and updates; the separate clawhub CLI handles login and publishing.

openclaw skills search "calendar"
openclaw skills install @owner/<slug>             # into <workspace>/skills
openclaw skills install @owner/<slug> --global    # into ~/.openclaw/skills, for all local agents
openclaw skills install git:owner/repo@main       # from a Git repository
openclaw skills install ./path/to/skill --as my-tool
openclaw skills update --all

Git and local installs need SKILL.md at the source root, and openclaw skills update only tracks ClawHub installs; reinstall the others to refresh them. If you use clawhub install instead, it writes to ./skills in the current directory and records versions in .clawhub/lock.json.

Running openclaw skills search with no query shows ClawHub’s trending feed. Lists such as the VoltAgent “awesome” list on GitHub sort ClawHub skills by category and say they left out 7,215, including 4,065 they marked as possible spam and 373 flagged as malicious by published security audits.

Are ClawHub skills safe to install?

Not by default. The OpenClaw docs say to treat third-party skills as untrusted code, read them before enabling, and run risky work in a sandbox. ClawHub is open: anyone with a GitHub account old enough to pass its upload gate can publish.

ClawHub scans each release (VirusTotal, its own ClawScan review, and static analysis) and shows the result on the skill page before you install. Its audit statuses mean:

A separate risk level (Low, Medium, High) says how much power the skill has. A publishing skill can show Review at Medium risk and be perfectly legitimate.

From the command line, openclaw skills verify @owner/<slug> checks the skill’s trust envelope against ClawHub and exits non-zero if verification failed. The docs also note that OpenClaw runs no local dangerous-code check during install. If you want one, set security.installPolicy to a command of your own; it runs before every ClawHub, Git, local and update install and fails closed.

A short checklist from the docs:

• Prefer known publishers and pinned versions (--version <version>).
• Read SKILL.md and every script before enabling.
• Keep agent allowlists narrow.
• Keep secrets out of skill files. skills.entries.<name>.env and apiKey inject them into the host process for one turn, and not into the sandbox.
• Run openclaw security audit --deep after config changes.

How do I write my own OpenClaw skill?

The steps from the creating skills page:

mkdir -p ~/.openclaw/workspace/skills/hello-world

Then write ~/.openclaw/workspace/skills/hello-world/SKILL.md:

---
name: hello-world
description: A simple skill that prints a greeting.
---

# Hello World

When the user asks for a greeting, use the `exec` tool to run:

```bash
echo "Hello from your custom skill!"
```

Check that it loaded with openclaw skills list, then test it with openclaw agent --message "give me a greeting" or /skill hello-world in chat.

Rules worth keeping:

• name uses lowercase letters, digits and hyphens, and matches the folder name.
• description is one line under 160 characters. Every eligible skill’s name, description and location go into the system prompt, at about 97 characters of overhead each (roughly 24 tokens) plus those fields. Fifty skills cost about 1,200 tokens before the fields are counted.
• If the skill runs exec, make sure untrusted input cannot inject commands.

OpenClaw can also draft skills itself. Skill Workshop puts the agent’s proposals in a queue you review with openclaw skills workshop list, inspect, evaluate and apply. To publish to ClawHub, run npm i -g clawhub, clawhub login, then clawhub skill publish ./path/to/hello-world.

OpenClaw skills vs Hermes Agent skills

Both use folders with a SKILL.md, and both follow the agentskills.io standard. The Hermes Agent skills guide covers the Hermes side in full. The differences that matter in practice:

We run several Hermes profiles on one Mac, and the pattern is the same one OpenClaw’s docs describe for agents: each keeps its own skills, and what one learns stays there until you share the folder. OpenClaw says it outright: Workshop skills learned by one agent are not shared with another, so publish them to the managed library when several agents need them.

~/.agents/skills is the overlap. OpenClaw reads it when it runs with the default state directory, and Hermes reads it when you add it to skills.external_dirs, so a skill kept to the common fields (name, description, plain instructions) could serve both. That comes from the two sets of docs; we have not tested it with OpenClaw. OpenClaw also includes a migrate-hermes plugin that imports Hermes configuration, memories and skills. The Hermes Agent vs OpenClaw guide compares the two agents more widely.

Share what skills learn with your other agents

Skills answer “how do I do this kind of task”. Most of what agents find out is something else: how a system works, what was decided and why, what an investigation turned up. That does not fit a skill, and a shared skills folder sits on one disk.

Dexio is a hosted wiki that OpenClaw, Hermes, Claude Code, Codex and your other agents read and write over MCP, so what one agent finds, the others can read. You see what your agents know as a page graph at https://app.dexio.wiki. It is open source (AGPL-3.0) and free for one person; Team is $10 and Business $20 a member a month.

To connect OpenClaw, send it this:

Connect yourself to my Dexio wiki. The steps are at https://dexio.wiki/agents.md: read the whole file, not a summary, and follow them.

Dexio’s instructions add the server to ~/.openclaw/openclaw.json with transport: "streamable-http" and check it with openclaw mcp doctor dexio --probe. The OpenClaw memory guide walks through it.

Then a small skill keeps every agent using the wiki the same way. Put it in ~/.agents/skills/dexio-wiki/SKILL.md:

---
name: dexio-wiki
description: Read and write the shared Dexio wiki before and after work on a topic it may cover.
---

# Dexio wiki

1. Call search_pages and read_page first. Update the page that exists.
2. Pass the base_version from read_page when you edit a page.
3. Link related pages.
4. Put your own agent name in the agent field on every change.

Never write API keys or passwords to the wiki.

The skill holds the procedure; the wiki holds what the procedure produces. For instructions that belong to one repository, see the AGENTS.md guide, and the OpenClaw setup guide covers installing OpenClaw itself.

FAQ

Where are installed OpenClaw skills stored? openclaw skills install puts them in the active workspace’s skills/ folder. With --global they go to ~/.openclaw/skills, which every local agent sees unless an allowlist narrows it.

Why doesn’t my skill show up? Run openclaw skills check. The usual causes are a missing binary or env var in metadata.openclaw.requires, an agent allowlist that leaves it out, or a session started before the skill existed.

Do skills use context? Yes: about 24 tokens per eligible skill plus its name, description and location. If the list passes skills.limits.maxSkillsPromptChars, OpenClaw shortens descriptions first, then drops them.

Can a skill hold an API key? Not in the file. Put it in skills.entries.<name>.apiKey or env in openclaw.json, ideally as a reference to an environment variable.

Sources

• https://docs.openclaw.ai/tools/skills
• https://docs.openclaw.ai/tools/creating-skills
• https://docs.openclaw.ai/cli/skills
• https://docs.openclaw.ai/clawhub
• https://docs.openclaw.ai/clawhub/security-audits
• https://docs.openclaw.ai/help/faq/security-and-access-control
• https://docs.openclaw.ai/plugins/reference/migrate-hermes
• https://github.com/VoltAgent/awesome-openclaw-skills
• https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
• https://dexio.wiki/agents.md