mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-03 19:24:05 +00:00
5976f14832
Rewrites all skills documentation pages with rich Mintlify components (Steps, CardGroup, AccordionGroup, ParamField, Note, Warning, Tip) and code-verified accuracy throughout. - tools/skills.md: CardGroup quick-nav, verified precedence table from workspace.ts, Security accordions, Steps for env injection, token impact formula, Related CardGroup - tools/creating-skills.md: Steps walkthrough, gating accordion, propose-update command (was missing), Best practices Tip, ClawHub publish flow, Related CardGroup - tools/skills-config.md: ParamField for every config key, agent allowlist section, Workshop config, sandbox Warning - tools/slash-commands.md: CardGroup for 3 command types, command tables in AccordionGroup sections, ParamFields for all config keys, dedicated sections for /tools /model /config /mcp /debug /plugins /trace /btw - prose.md: Steps for install, CardGroup quick-nav, AccordionGroup for state backends, runtime mapping table docs.json: adds skill-workshop nav entry and redirects (/skill-workshop, /tools/skills-workshop -> /tools/skill-workshop)
22 KiB
22 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:
<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).
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 them via metadata.openclaw.requires.config on the
plugin's config entry.
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 <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>`.
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. 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. Gateway-backed skill installs (onboarding, Skills settings UI) run the built-in dangerous-code scanner before executing installer metadata. `critical` findings block by default; `suspicious` findings warn only. `openclaw skills install ` downloads a ClawHub skill folder directly and does not use the installer-metadata scanner. `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 (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
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,
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.
Token impact
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))
- Base overhead (only when ≥ 1 skill): ~195 characters
- 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
Keep descriptions short and descriptive to minimize prompt overhead.