f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
24 KiB
title, sidebarTitle, summary, read_when
| title | sidebarTitle | summary | read_when | |||
|---|---|---|---|---|---|---|
| Skills | Skills | Skills teach your agent how to use tools. Learn how they load, how precedence works, and how to configure gating, allowlists, and environment injection. |
|
Skills are markdown instruction files that teach the agent how and when to use
tools. Each skill lives in a directory containing a SKILL.md file with YAML
frontmatter and a markdown body. OpenClaw loads bundled skills plus any local
overrides, and filters them at load time based on environment, config, and
binary presence.
Loading order
OpenClaw loads from these sources, highest precedence first. When the same skill name appears in multiple places, the highest source wins.
| Priority | Source | Path |
|---|---|---|
| 1 — highest | Workspace skills | <workspace>/skills |
| 2 | Project agent skills | <workspace>/.agents/skills |
| 3 | Personal agent skills | ~/.agents/skills |
| 4 | Managed / local skills | ~/.openclaw/skills |
| 5 | Bundled skills | shipped with the install |
| 6 — lowest | Extra directories | skills.load.extraDirs + plugin skills |
Skill roots support grouped layouts. OpenClaw discovers a skill whenever
SKILL.md appears anywhere under a configured root (up to 6 levels deep):
<workspace>/skills/research/SKILL.md ✓ found as "research"
<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"
The folder path is for organization only. The skill's name and slash command
come from the name frontmatter field (or the directory name when name is
missing). Agent allowlists (below) also match on this name.
Per-agent vs shared skills
In multi-agent setups, each agent has its own workspace. Use the path that matches your desired visibility:
| Scope | Path | Visible to |
|---|---|---|
| Per-agent | <workspace>/skills |
Only that agent |
| Project-agent | <workspace>/.agents/skills |
Only that workspace's agent |
| Personal-agent | ~/.agents/skills |
All agents on this machine |
| Shared managed | ~/.openclaw/skills |
All agents on this machine |
| Extra dirs | skills.load.extraDirs |
All agents on this machine |
Agent allowlists
Skill location (precedence) and skill visibility (which agent can use it) are separate controls. Use allowlists to restrict which skills an agent sees, regardless of where they are loaded from.
{
agents: {
defaults: {
skills: ["github", "weather"], // shared baseline
},
list: [
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults entirely
{ id: "locked-down", skills: [] }, // no skills
],
},
}
Plugins and skills
Plugins can ship their own skills by listing skills directories in
openclaw.plugin.json (paths relative to the plugin root). Plugin skills load
when the plugin is enabled — for example, the browser plugin ships a
browser-automation skill for multi-step browser control.
Plugin skill directories merge at the same low-precedence level as
skills.load.extraDirs, so a same-named bundled, managed, agent, or workspace
skill overrides them. Gate a plugin skill's own eligibility via
metadata.openclaw.requires in its frontmatter, same as any other skill.
See Plugins and Tools for the full plugin system.
Skill Workshop
Skill Workshop is a proposal queue between the agent
and your active skill files. When the agent spots reusable work, it drafts a
proposal instead of writing directly to SKILL.md. You review and approve
before anything changes.
openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>
See Skill Workshop for the full lifecycle, CLI reference, and configuration.
Installing from ClawHub
ClawHub is the public skills registry. Use
openclaw skills commands for install and update, or the clawhub CLI for
publish and sync.
| Action | Command |
|---|---|
| Install a skill into the workspace | openclaw skills install @owner/<slug> |
| Install from a Git repository | openclaw skills install git:owner/repo@ref |
| Install a local skill directory | openclaw skills install ./path/to/skill --as my-tool |
| Install for all local agents | openclaw skills install @owner/<slug> --global |
| Update all workspace skills | openclaw skills update --all |
| Update a shared managed skill | openclaw skills update @owner/<slug> --global |
| Update all shared managed skills | openclaw skills update --all --global |
| Verify a skill's trust envelope | openclaw skills verify @owner/<slug> |
| Print the generated Skill Card | openclaw skills verify @owner/<slug> --card |
| Publish / sync via ClawHub CLI | clawhub sync --all |
Git and local installs expect `SKILL.md` at the source root. The slug comes
from `SKILL.md` frontmatter `name` when valid, then falls back to the
directory or repository name. Use `--as <slug>` to override.
`openclaw skills update` tracks ClawHub installs only — reinstall Git or
local sources to refresh them.
ClawHub skill pages expose the latest security scan state before install,
with detail pages for VirusTotal, ClawScan, and static analysis. The
command exits non-zero when ClawHub marks verification as failed. Publishers
recover false positives through the ClawHub dashboard or
`clawhub skill rescan @owner/<slug>`.
Security
Treat third-party skills as **untrusted code**. Read them before enabling. Prefer sandboxed runs for untrusted inputs and risky tools. See [Sandboxing](/gateway/sandboxing) for agent-side controls. Workspace, project-agent, and extra-dir skill discovery only accepts skill roots whose resolved realpath stays inside the configured root, unless `skills.load.allowSymlinkTargets` explicitly trusts a target root. Skill Workshop writes through those trusted targets only when `skills.workshop.allowSymlinkTargetWrites` is enabled. Managed `~/.openclaw/skills` and personal `~/.agents/skills` may contain symlinked skill folders, but every `SKILL.md` realpath must still stay inside its resolved skill directory. Configure `security.installPolicy` to run a trusted local policy command before skill installs continue. The policy receives metadata and the staged source path, applies to ClawHub, uploaded, Git, local, update, and dependency-installer paths, and fails closed when the command cannot return a valid decision. `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process for that agent turn only — not into the sandbox. Keep secrets out of prompts and logs.For the broader threat model and security checklists, see Security.
SKILL.md format
Every skill needs at minimum a name and description in the frontmatter:
---
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...
Optional frontmatter keys
URL shown as "Website" in the macOS Skills UI. Also supported via `metadata.openclaw.homepage`. When `true`, the skill is exposed as a user-invocable slash command. When `true`, OpenClaw keeps the skill's instructions out of the agent's normal prompt. The skill is still available as a slash command when `user-invocable` is also `true`. When set to `tool`, the slash command bypasses the model and dispatches directly to a registered tool. Tool name to invoke when `command-dispatch: tool` is set. For tool dispatch, forwards the raw args string to the tool with no core parsing. The tool receives `{ command: "", commandName: "", skillName: "" }`.Gating
OpenClaw filters skills at load time using metadata.openclaw (JSON5 object
embedded in the frontmatter, see the parsing note above). A skill with no
metadata.openclaw block is always eligible unless explicitly disabled.
---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
{
"openclaw":
{
"requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
"primaryEnv": "GEMINI_API_KEY",
},
}
---
Installer specs
Installer specs tell the macOS Skills UI how to install a dependency:
---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
{
"openclaw":
{
"emoji": "♊️",
"requires": { "bins": ["gemini"] },
"install":
[
{
"id": "brew",
"kind": "brew",
"formula": "gemini-cli",
"bins": ["gemini"],
"label": "Install Gemini CLI (brew)",
},
],
},
}
---
Config overrides
Toggle and configure bundled or managed skills under skills.entries in
~/.openclaw/openclaw.json:
{
skills: {
entries: {
"image-lab": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
config: {
endpoint: "https://example.invalid",
model: "nano-pro",
},
},
peekaboo: { enabled: true },
sag: { enabled: false },
},
},
}
Environment injection
When an agent run starts, OpenClaw:
OpenClaw resolves the effective skill list for the agent, applying gating rules, allowlists, and config overrides. `skills.entries..env` and `skills.entries..apiKey` are applied to `process.env` for the duration of the run. Eligible skills are compiled into a compact XML block and injected into the system prompt. After the run ends, the original environment is restored. Env injection is scoped to the **host** agent run, not the sandbox. Inside a sandbox, `env` and `apiKey` have no effect. See [Skills config](/tools/skills-config#sandboxed-skills-and-env-vars) for how to pass secrets into sandboxed runs.For the bundled claude-cli backend, OpenClaw also materializes the same
eligible skill snapshot as a temporary Claude Code plugin and passes it via
--plugin-dir. Other CLI backends use the prompt catalog only.
Snapshots and refresh
OpenClaw snapshots eligible skills when a session starts and reuses that list for all subsequent turns in the session. Changes to skills or config take effect on the next new session.
Skills refresh mid-session in two cases:
- The skills watcher detects a
SKILL.mdchange. - A new eligible remote node connects.
The refreshed list is picked up on the next agent turn. If the effective agent allowlist changes, OpenClaw refreshes the snapshot to keep visible skills aligned.
By default, OpenClaw watches skill folders and bumps the snapshot when `SKILL.md` files change. Configure under `skills.load`:```json5
{
skills: {
load: {
extraDirs: ["~/Projects/agent-scripts/skills"],
allowSymlinkTargets: ["~/Projects/manager/skills"],
watch: true, // default
watchDebounceMs: 250, // default
},
},
}
```
Use `allowSymlinkTargets` for intentional symlinked layouts where a skill
root symlink points outside the configured root, for example
`<workspace>/skills/manager -> ~/Projects/manager/skills`.
Enable `skills.workshop.allowSymlinkTargetWrites` only when Skill Workshop
should also apply proposals through those trusted symlinked paths.
Offline nodes do **not** make remote-only skills visible. If a node stops
answering bin probes, OpenClaw clears its cached bin matches.
Token impact
When skills are eligible, OpenClaw injects a compact XML block into the system prompt. The cost is deterministic and scales linearly per skill:
- Base overhead (only when 1+ skills are eligible): a fixed block of intro
prose plus the
<available_skills>wrapper. - Per skill: ~97 characters + your
name,description, andlocationfield lengths. - XML escaping expands
& < > " 'into entities, adding a few characters per occurrence. - At ~4 chars/token, 97 chars ≈ 24 tokens per skill before field lengths.
If the rendered block would exceed the configured prompt budget
(skills.limits.maxSkillsPromptChars), OpenClaw first drops descriptions
(compact format: name + location only), then truncates the skill list and adds
a note pointing at openclaw skills check.
Keep descriptions short and descriptive to minimize prompt overhead.