docs/tools/skills.md
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.
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:
<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, slash command, and
allowlist key all come from the name frontmatter field (or the directory name
when name is missing).
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 |
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 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 them via metadata.openclaw.requires.config on the
plugin's config entry.
See Plugins and Tools for the full plugin system.
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.
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 <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 <slug> --global |
| Update all workspace skills | openclaw skills update --all |
| Update a shared managed skill | openclaw skills update <slug> --global |
| Update all shared managed skills | openclaw skills update --all --global |
| Verify a skill's trust envelope | openclaw skills verify <slug> |
| Print the generated Skill Card | openclaw skills verify <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 <slug>`.
For the broader threat model and security checklists, see Security.
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...
OpenClaw filters skills at load time using metadata.openclaw (single-line
JSON in the frontmatter). 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 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)",
},
],
},
}
---
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 },
},
},
}
When an agent run starts, OpenClaw:
<Steps> <Step title="Reads skill metadata"> OpenClaw resolves the effective skill list for the agent, applying gating rules, allowlists, and config overrides. </Step> <Step title="Injects env and API keys"> `skills.entries.<key>.env` and `skills.entries.<key>.apiKey` are applied to `process.env` for the duration of the run. </Step> <Step title="Builds the system prompt"> Eligible skills are compiled into a compact XML block and injected into the system prompt. </Step> <Step title="Restores the environment"> After the run ends, the original environment is restored. </Step> </Steps> <Warning> 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. </Warning>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.
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:
SKILL.md change.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.
<AccordionGroup> <Accordion title="Skills watcher"> 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,
watchDebounceMs: 250,
},
},
}
```
Use `allowSymlinkTargets` for intentional symlinked layouts where a skill
root symlink points outside the configured root, for example
`<workspace>/skills/manager -> ~/Projects/manager/skills`.
Offline nodes do **not** make remote-only skills visible. If a node stops
answering bin probes, OpenClaw clears its cached bin matches.
When skills are eligible, OpenClaw injects a compact XML block into the system prompt. The cost is deterministic:
total = 195 + Σ (97 + len(name) + len(description) + len(filepath))
name, description, and location field lengths& < > " ' into entities, adding a few characters per occurrenceKeep descriptions short and descriptive to minimize prompt overhead.