3b347d1c7e
Merged via squash.
Prepared head SHA: 63bac4340f
Co-authored-by: mbelinky <132747814+mbelinky@users.noreply.github.com>
Co-authored-by: mbelinky <132747814+mbelinky@users.noreply.github.com>
Reviewed-by: @mbelinky
20 KiB
summary, read_when, title, sidebarTitle
| summary | read_when | title | sidebarTitle | |||
|---|---|---|---|---|---|---|
| Skills: managed vs workspace, gating rules, agent allowlists, and config wiring |
|
Skills | Skills |
OpenClaw uses AgentSkills-compatible skill
folders to teach the agent how to use tools. Each skill is a directory
containing a SKILL.md with YAML frontmatter and instructions. OpenClaw
loads bundled skills plus optional local overrides, and filters them at
load time based on environment, config, and binary presence.
Locations and precedence
OpenClaw loads skills from these sources, highest precedence first:
| # | Source | Path |
|---|---|---|
| 1 | 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 | Extra skill folders | skills.load.extraDirs (config) |
If a skill name conflicts, the highest source wins.
Codex CLI's native $CODEX_HOME/skills directory is not one of these OpenClaw
skill roots. In Codex harness mode, local app-server launches use isolated
per-agent Codex homes, so personal Codex CLI skills are not loaded implicitly.
Use openclaw migrate codex --dry-run to inventory them and
openclaw migrate codex to choose skill directories with an interactive
checkbox prompt before copying them into the current OpenClaw agent workspace.
For non-interactive runs, repeat --skill <name> for the exact skills to copy.
Per-agent vs shared skills
In multi-agent setups each agent has its own workspace:
| 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 that machine |
| Shared managed/local | ~/.openclaw/skills |
All agents on that machine |
| Shared extra dirs | skills.load.extraDirs (lowest precedence) |
All agents on that machine |
Same name in multiple places → highest source wins. Workspace beats project-agent, beats personal-agent, beats managed/local, beats bundled, beats extra dirs.
Agent skill allowlists
Skill location and skill visibility are separate controls. Location/precedence decides which copy of a same-named skill wins; agent allowlists decide which skills an agent can actually use.
{
agents: {
defaults: {
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
{ 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. This is the right place for tool-specific
operating guides that are too long for the tool description but should be
available whenever the plugin is installed — for example, the browser
plugin ships a browser-automation skill for multi-step browser control.
Plugin skill directories are merged into the same low-precedence path as
skills.load.extraDirs, so a same-named bundled, managed, agent, or
workspace skill overrides them. You can gate them via
metadata.openclaw.requires.config on the plugin's config entry.
See Plugins for discovery/config and Tools for the tool surface those skills teach.
Skill Workshop
The optional, experimental Skill Workshop plugin can create or update
workspace skills from reusable procedures observed during agent work. It
is disabled by default and must be explicitly enabled via
plugins.entries.skill-workshop.
Skill Workshop writes only to <workspace>/skills, scans generated
content, supports pending approval or automatic safe writes, quarantines
unsafe proposals, and refreshes the skill snapshot after successful
writes so new skills become available without a Gateway restart.
Use it for corrections such as "next time, verify GIF attribution" or hard-won workflows such as media QA checklists. Start with pending approval; use automatic writes only in trusted workspaces after reviewing its proposals. Full guide: Skill Workshop plugin.
ClawHub (install and sync)
ClawHub is the public skills registry for OpenClaw.
Use native openclaw skills commands for discover/install/update, or the
separate clawhub CLI for publish/sync workflows. Full guide:
ClawHub.
| Action | Command |
|---|---|
| Install a skill into the workspace | openclaw skills install <skill-slug> |
| Update all installed skills | openclaw skills update --all |
| Sync (scan + publish updates) | clawhub sync --all |
Native openclaw skills install installs into the active workspace
skills/ directory. The separate clawhub CLI also installs into
./skills under your current working directory (or falls back to the
configured OpenClaw workspace). OpenClaw picks that up as
<workspace>/skills on the next session.
Configured skill roots also support one grouping level, such as
skills/<group>/<skill>/SKILL.md, so related third-party skills can be
kept under a shared folder without broad recursive scanning.
ClawHub skill pages expose the latest security scan state before install,
with scanner detail pages for VirusTotal, ClawScan, and static analysis.
openclaw skills install <slug> remains only the install path; 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 the agent-side controls.- Workspace and extra-dir skill discovery only accepts skill roots and
SKILL.mdfiles whose resolved realpath stays inside the configured root. - Gateway-backed skill dependency installs (
skills.install, onboarding, and the Skills settings UI) run the built-in dangerous-code scanner before executing installer metadata.criticalfindings block by default unless the caller explicitly sets the dangerous override; suspicious findings still warn only. openclaw skills install <slug>is different — it downloads a ClawHub skill folder into the workspace and does not use the installer-metadata path above.skills.entries.*.envandskills.entries.*.apiKeyinject secrets into the host process for that agent turn (not the sandbox). Keep secrets out of prompts and logs.
For a broader threat model and checklists, see Security.
SKILL.md format
SKILL.md must include at least:
---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---
OpenClaw follows the AgentSkills spec for layout/intent. The parser used
by the embedded agent supports single-line frontmatter keys only;
metadata should be a single-line JSON object. Use {baseDir} in
instructions to reference the skill folder path.
Optional frontmatter keys
URL surfaced as "Website" in the macOS Skills UI. Also supported via `metadata.openclaw.homepage`. When `true`, the skill is exposed as a user slash command. When `true`, OpenClaw keeps the skill's instructions out of the agent's normal prompt. The skill is still installed and can still be run explicitly 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 tool. Tool name to invoke when `command-dispatch: tool` is set. For tool dispatch, forwards the raw args string to the tool (no core parsing). The tool is invoked with `{ command: "", commandName: "", skillName: "" }`.Gating (load-time filters)
OpenClaw filters skills at load time using metadata (single-line JSON):
---
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",
},
}
---
Fields under metadata.openclaw:
If no metadata.openclaw is present, the skill is always eligible (unless
disabled in config or blocked by skills.allowBundled for bundled skills).
Sandboxing notes
requires.binsis checked on the host at skill load time.- If an agent is sandboxed, the binary must also exist inside the container. Install it via
agents.defaults.sandbox.docker.setupCommand(or a custom image).setupCommandruns once after the container is created. Package installs also require network egress, a writable root FS, and a root user in the sandbox. - Example: the
summarizeskill (skills/summarize/SKILL.md) needs thesummarizeCLI in the sandbox container to run there.
Installer specs
---
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
Bundled and managed skills can be toggled and supplied with env values
under skills.entries in ~/.openclaw/openclaw.json:
{
skills: {
entries: {
"image-lab": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
env: {
GEMINI_API_KEY: "GEMINI_KEY_HERE",
},
config: {
endpoint: "https://example.invalid",
model: "nano-pro",
},
},
peekaboo: { enabled: true },
sag: { enabled: false },
},
},
}
If the skill name contains hyphens, quote the key (JSON5 allows quoted
keys). Config keys match the skill name by default — if a skill
defines metadata.openclaw.skillKey, use that key under skills.entries.
Environment injection
When an agent run starts, OpenClaw:
- Reads skill metadata.
- Applies
skills.entries.<key>.envandskills.entries.<key>.apiKeytoprocess.env. - Builds the system prompt with eligible skills.
- Restores the original environment after the run ends.
Environment injection is scoped to the agent run, not a global shell environment.
For the bundled claude-cli backend, OpenClaw also materializes the same
eligible snapshot as a temporary Claude Code plugin and passes it with
--plugin-dir. Claude Code can then use its native skill resolver while
OpenClaw still owns precedence, per-agent allowlists, gating, and
skills.entries.* env/API key injection. Other CLI backends use the
prompt catalog only.
Snapshots and refresh
OpenClaw snapshots the eligible skills when a session starts and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
Skills can refresh mid-session in two cases:
- The skills watcher is enabled.
- A new eligible remote node appears.
Think of this as a hot reload: the refreshed list is picked up on the next agent turn. If the effective agent skill allowlist changes for that session, OpenClaw refreshes the snapshot so visible skills stay aligned with the current agent.
Skills watcher
By default, OpenClaw watches skill folders and bumps the skills snapshot
when SKILL.md files change. Configure under skills.load:
{
skills: {
load: {
watch: true,
watchDebounceMs: 250,
},
},
}
Remote macOS nodes (Linux gateway)
If the Gateway runs on Linux but a macOS node is connected with
system.run allowed (Exec approvals security not set to deny),
OpenClaw can treat macOS-only skills as eligible when the required
binaries are present on that node. The agent should execute those skills
via the exec tool with host=node.
This relies on the node reporting its command support and on a bin probe
via system.which or system.run. Offline nodes do not make
remote-only skills visible. If a connected node stops answering bin
probes, OpenClaw clears its cached bin matches so agents no longer see
skills that cannot currently run there.
Token impact
When skills are eligible, OpenClaw injects a compact XML list of available
skills into the system prompt (via formatSkillsForPrompt in
pi-coding-agent). The cost is deterministic:
- Base overhead (only when ≥1 skill): 195 characters.
- Per skill: 97 characters + the length of the XML-escaped
<name>,<description>, and<location>values.
Formula (characters):
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
XML escaping expands & < > " ' into entities (&, <, etc.),
increasing length. Token counts vary by model tokenizer. A rough
OpenAI-style estimate is ~4 chars/token, so 97 chars ≈ 24 tokens per
skill plus your actual field lengths.
Managed skills lifecycle
OpenClaw ships a baseline set of skills as bundled skills with the
install (npm package or OpenClaw.app). ~/.openclaw/skills exists for
local overrides — for example, pinning or patching a skill without
changing the bundled copy. Workspace skills are user-owned and override
both on name conflicts.
Looking for more skills?
Browse https://clawhub.ai. Full configuration schema: Skills config.
Related
- ClawHub — public skills registry
- Creating skills — building custom skills
- Plugins — plugin system overview
- Skill Workshop plugin — generate skills from agent work
- Skills config — skill configuration reference
- Slash commands — all available slash commands