Skills

• Omit agents.defaults.skills to leave all skills unrestricted by default.
• Omit agents.list[].skills to inherit agents.defaults.skills.
• Set agents.list[].skills: [] to expose no skills for that agent.
• A non-empty agents.list[].skills list is the final set — it does not merge with defaults.
• The effective allowlist applies across prompt building, slash-command discovery, sandbox sync, and skill snapshots.
• This is not a host shell authorization boundary. If the same agent can use exec, constrain that shell separately with sandboxing, OS-user isolation, exec deny/allowlists, and per-resource credentials.

openclaw skills install installs into the active workspace skills/ directory by default. Add --global to install into the shared ~/.openclaw/skills directory, visible to all local agents unless agent allowlists narrow it.

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.

openclaw skills verify @owner/<slug> asks ClawHub for the skill's clawhub.skill.verify.v1 trust envelope. Installed ClawHub skills verify against the version and registry recorded in .clawhub/origin.json. Bare slugs remain accepted for existing installed or unambiguous skills, but owner-qualified refs avoid publisher ambiguity.

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>.

Gateway clients that need non-ClawHub delivery can stage a zip skill archive with skills.upload.begin, skills.upload.chunk, and skills.upload.commit, then install with skills.install({ source: "upload", ... }). This path is off by default and requires skills.install.allowUploadedArchives: true in openclaw.json. Normal ClawHub installs never need that setting.

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.

• When multiple installers are listed, the gateway picks one preferred option (brew when available, otherwise node).
• If all installers are download, OpenClaw lists each entry so you can see all available artifacts.
• Specs can include os: ["darwin"|"linux"|"win32"] to filter by platform.
• Node installs honor skills.install.nodeManager in openclaw.json (default: npm; options: npm / pnpm / yarn / bun). This only affects skill installs; the Gateway runtime should still be Node.
• Gateway installer preference: Homebrew → uv → configured node manager → go → download.

• Homebrew: OpenClaw does not auto-install Homebrew or translate brew formulas into system package commands. In Linux containers without brew, brew-only installers are hidden; use a custom image or install the dependency manually.
• Go: OpenClaw requires Go 1.21 or newer for automatic skill installs. If go is missing and Homebrew is available, OpenClaw installs Go via Homebrew first; on Linux without Homebrew it can instead use apt-get as root or through passwordless sudo when the refreshed golang-go candidate meets the minimum version. The actual go install for the dependency always targets a dedicated OpenClaw-managed bin directory (Homebrew's bin on a fresh install, else ~/.local/bin) rather than your configured GOBIN — your own GOBIN, GOPATH, and GOTOOLCHAIN env vars are read but never overwritten.
• Download: url (required), archive (tar.gz | tar.bz2 | zip), extract (default: auto when archive detected), stripComponents, targetDir (default: ~/.openclaw/tools/<skillKey>).

requires.bins is checked on the host at skill load time. If an agent runs in a sandbox, the binary must also exist inside the container. Install it via agents.defaults.sandbox.docker.setupCommand or a custom image. setupCommand runs once after container creation and requires network egress, a writable root FS, and a root user in the sandbox.

By default, OpenClaw watches skill folders and bumps the snapshot when SKILL.md files change. Configure under skills.load:

{  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.

If the Gateway runs on Linux but a macOS node is connected with system.run allowed, OpenClaw can treat macOS-only skills as eligible when the required binaries are present on that node. The agent should run those skills via the exec tool with host=node.

Offline nodes do not make remote-only skills visible. If a node stops answering bin probes, OpenClaw clears its cached bin matches.