openclaw-skill/openclaw-knowhow-skill/output/openclaw-docs_data/pages/Skills_OpenClaw_08398a115d.json

{
  "title": "Skills (OpenClaw)",
  "content": "OpenClaw uses **[AgentSkills](https://agentskills.io)-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.\n\n## Locations and precedence\n\nSkills are loaded from **three** places:\n\n1. **Bundled skills**: shipped with the install (npm package or OpenClaw\\.app)\n2. **Managed/local skills**: `~/.openclaw/skills`\n3. **Workspace skills**: `<workspace>/skills`\n\nIf a skill name conflicts, precedence is:\n\n`<workspace>/skills` (highest) → `~/.openclaw/skills` → bundled skills (lowest)\n\nAdditionally, you can configure extra skill folders (lowest precedence) via\n`skills.load.extraDirs` in `~/.openclaw/openclaw.json`.\n\n## Per-agent vs shared skills\n\nIn **multi-agent** setups, each agent has its own workspace. That means:\n\n* **Per-agent skills** live in `<workspace>/skills` for that agent only.\n* **Shared skills** live in `~/.openclaw/skills` (managed/local) and are visible\n  to **all agents** on the same machine.\n* **Shared folders** can also be added via `skills.load.extraDirs` (lowest\n  precedence) if you want a common skills pack used by multiple agents.\n\nIf the same skill name exists in more than one place, the usual precedence\napplies: workspace wins, then managed/local, then bundled.\n\nPlugins can ship their own skills by listing `skills` directories in\n`openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load\nwhen the plugin is enabled and participate in the normal skill precedence rules.\nYou can gate them via `metadata.openclaw.requires.config` on the plugin’s config\nentry. See [Plugins](/plugin) for discovery/config and [Tools](/tools) for the\ntool surface those skills teach.\n\n## ClawHub (install + sync)\n\nClawHub is the public skills registry for OpenClaw. Browse at\n[https://clawhub.com](https://clawhub.com). Use it to discover, install, update, and back up skills.\nFull guide: [ClawHub](/tools/clawhub).\n\n* Install a skill into your workspace:\n  * `clawhub install <skill-slug>`\n* Update all installed skills:\n  * `clawhub update --all`\n* Sync (scan + publish updates):\n  * `clawhub sync --all`\n\nBy default, `clawhub` installs into `./skills` under your current working\ndirectory (or falls back to the configured OpenClaw workspace). OpenClaw picks\nthat up as `<workspace>/skills` on the next session.\n\n* Treat third-party skills as **untrusted code**. Read them before enabling.\n* Prefer sandboxed runs for untrusted inputs and risky tools. See [Sandboxing](/gateway/sandboxing).\n* `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process\n  for that agent turn (not the sandbox). Keep secrets out of prompts and logs.\n* For a broader threat model and checklists, see [Security](/gateway/security).\n\n## Format (AgentSkills + Pi-compatible)\n\n`SKILL.md` must include at least:\n\n* We follow the AgentSkills spec for layout/intent.\n* The parser used by the embedded agent supports **single-line** frontmatter keys only.\n* `metadata` should be a **single-line JSON object**.\n* Use `{baseDir}` in instructions to reference the skill folder path.\n* Optional frontmatter keys:\n  * `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.openclaw.homepage`).\n  * `user-invocable` — `true|false` (default: `true`). When `true`, the skill is exposed as a user slash command.\n  * `disable-model-invocation` — `true|false` (default: `false`). When `true`, the skill is excluded from the model prompt (still available via user invocation).\n  * `command-dispatch` — `tool` (optional). When set to `tool`, the slash command bypasses the model and dispatches directly to a tool.\n  * `command-tool` — tool name to invoke when `command-dispatch: tool` is set.\n  * `command-arg-mode` — `raw` (default). For tool dispatch, forwards the raw args string to the tool (no core parsing).\n\nThe tool is invoked with params:\n    `{ command: \"<raw args>\", commandName: \"<slash command>\", skillName: \"<skill name>\" }`.\n\n## Gating (load-time filters)\n\nOpenClaw **filters skills at load time** using `metadata` (single-line JSON):\n\nFields under `metadata.openclaw`:\n\n* `always: true` — always include the skill (skip other gates).\n* `emoji` — optional emoji used by the macOS Skills UI.\n* `homepage` — optional URL shown as “Website” in the macOS Skills UI.\n* `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes.\n* `requires.bins` — list; each must exist on `PATH`.\n* `requires.anyBins` — list; at least one must exist on `PATH`.\n* `requires.env` — list; env var must exist **or** be provided in config.\n* `requires.config` — list of `openclaw.json` paths that must be truthy.\n* `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.\n* `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv/download).\n\n* `requires.bins` is checked on the **host** at skill load time.\n* If an agent is sandboxed, the binary must also exist **inside the container**.\n  Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image).\n  `setupCommand` runs once after the container is created.\n  Package installs also require network egress, a writable root FS, and a root user in the sandbox.\n  Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI\n  in the sandbox container to run there.\n\n* If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).\n* If all installers are `download`, OpenClaw lists each entry so you can see the available artifacts.\n* Installer specs can include `os: [\"darwin\"|\"linux\"|\"win32\"]` to filter options by platform.\n* Node installs honor `skills.install.nodeManager` in `openclaw.json` (default: npm; options: npm/pnpm/yarn/bun).\n  This only affects **skill installs**; the Gateway runtime should still be Node\n  (Bun is not recommended for WhatsApp/Telegram).\n* Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.\n* Download installs: `url` (required), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (default: auto when archive detected), `stripComponents`, `targetDir` (default: `~/.openclaw/tools/<skillKey>`).\n\nIf no `metadata.openclaw` is present, the skill is always eligible (unless\ndisabled in config or blocked by `skills.allowBundled` for bundled skills).\n\n## Config overrides (`~/.openclaw/openclaw.json`)\n\nBundled/managed skills can be toggled and supplied with env values:\n\nNote: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).\n\nConfig keys match the **skill name** by default. If a skill defines\n`metadata.openclaw.skillKey`, use that key under `skills.entries`.\n\n* `enabled: false` disables the skill even if it’s bundled/installed.\n* `env`: injected **only if** the variable isn’t already set in the process.\n* `apiKey`: convenience for skills that declare `metadata.openclaw.primaryEnv`.\n* `config`: optional bag for custom per-skill fields; custom keys must live here.\n* `allowBundled`: optional allowlist for **bundled** skills only. If set, only\n  bundled skills in the list are eligible (managed/workspace skills unaffected).\n\n## Environment injection (per agent run)\n\nWhen an agent run starts, OpenClaw:\n\n1. Reads skill metadata.\n2. Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to\n   `process.env`.\n3. Builds the system prompt with **eligible** skills.\n4. Restores the original environment after the run ends.\n\nThis is **scoped to the agent run**, not a global shell environment.\n\n## Session snapshot (performance)\n\nOpenClaw 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.\n\nSkills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears (see below). Think of this as a **hot reload**: the refreshed list is picked up on the next agent turn.\n\n## Remote macOS nodes (Linux gateway)\n\nIf the Gateway is running 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 `nodes` tool (typically `nodes.run`).\n\nThis relies on the node reporting its command support and on a bin probe via `system.run`. If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects.\n\n## Skills watcher (auto-refresh)\n\nBy default, OpenClaw watches skill folders and bumps the skills snapshot when `SKILL.md` files change. Configure this under `skills.load`:\n\n## Token impact (skills list)\n\nWhen 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:\n\n* **Base overhead (only when ≥1 skill):** 195 characters.\n* **Per skill:** 97 characters + the length of the XML-escaped `<name>`, `<description>`, and `<location>` values.\n\nFormula (characters):\n\n* XML escaping expands `& < > \" '` into entities (`&amp;`, `&lt;`, etc.), increasing length.\n* 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.\n\n## Managed skills lifecycle\n\nOpenClaw ships a baseline set of skills as **bundled skills** as part of the\ninstall (npm package or OpenClaw\\.app). `~/.openclaw/skills` exists for local\noverrides (for example, pinning/patching a skill without changing the bundled\ncopy). Workspace skills are user-owned and override both on name conflicts.\n\nSee [Skills config](/tools/skills-config) for the full configuration schema.\n\n## Looking for more skills?\n\nBrowse [https://clawhub.com](https://clawhub.com).",
  "code_samples": [
    {
      "code": "Notes:\n\n* We follow the AgentSkills spec for layout/intent.\n* The parser used by the embedded agent supports **single-line** frontmatter keys only.\n* `metadata` should be a **single-line JSON object**.\n* Use `{baseDir}` in instructions to reference the skill folder path.\n* Optional frontmatter keys:\n  * `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.openclaw.homepage`).\n  * `user-invocable` — `true|false` (default: `true`). When `true`, the skill is exposed as a user slash command.\n  * `disable-model-invocation` — `true|false` (default: `false`). When `true`, the skill is excluded from the model prompt (still available via user invocation).\n  * `command-dispatch` — `tool` (optional). When set to `tool`, the slash command bypasses the model and dispatches directly to a tool.\n  * `command-tool` — tool name to invoke when `command-dispatch: tool` is set.\n  * `command-arg-mode` — `raw` (default). For tool dispatch, forwards the raw args string to the tool (no core parsing).\n\n    The tool is invoked with params:\n    `{ command: \"<raw args>\", commandName: \"<slash command>\", skillName: \"<skill name>\" }`.\n\n## Gating (load-time filters)\n\nOpenClaw **filters skills at load time** using `metadata` (single-line JSON):",
      "language": "unknown"
    },
    {
      "code": "Fields under `metadata.openclaw`:\n\n* `always: true` — always include the skill (skip other gates).\n* `emoji` — optional emoji used by the macOS Skills UI.\n* `homepage` — optional URL shown as “Website” in the macOS Skills UI.\n* `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes.\n* `requires.bins` — list; each must exist on `PATH`.\n* `requires.anyBins` — list; at least one must exist on `PATH`.\n* `requires.env` — list; env var must exist **or** be provided in config.\n* `requires.config` — list of `openclaw.json` paths that must be truthy.\n* `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.\n* `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv/download).\n\nNote on sandboxing:\n\n* `requires.bins` is checked on the **host** at skill load time.\n* If an agent is sandboxed, the binary must also exist **inside the container**.\n  Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image).\n  `setupCommand` runs once after the container is created.\n  Package installs also require network egress, a writable root FS, and a root user in the sandbox.\n  Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI\n  in the sandbox container to run there.\n\nInstaller example:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).\n* If all installers are `download`, OpenClaw lists each entry so you can see the available artifacts.\n* Installer specs can include `os: [\"darwin\"|\"linux\"|\"win32\"]` to filter options by platform.\n* Node installs honor `skills.install.nodeManager` in `openclaw.json` (default: npm; options: npm/pnpm/yarn/bun).\n  This only affects **skill installs**; the Gateway runtime should still be Node\n  (Bun is not recommended for WhatsApp/Telegram).\n* Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.\n* Download installs: `url` (required), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (default: auto when archive detected), `stripComponents`, `targetDir` (default: `~/.openclaw/tools/<skillKey>`).\n\nIf no `metadata.openclaw` is present, the skill is always eligible (unless\ndisabled in config or blocked by `skills.allowBundled` for bundled skills).\n\n## Config overrides (`~/.openclaw/openclaw.json`)\n\nBundled/managed skills can be toggled and supplied with env values:",
      "language": "unknown"
    },
    {
      "code": "Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).\n\nConfig keys match the **skill name** by default. If a skill defines\n`metadata.openclaw.skillKey`, use that key under `skills.entries`.\n\nRules:\n\n* `enabled: false` disables the skill even if it’s bundled/installed.\n* `env`: injected **only if** the variable isn’t already set in the process.\n* `apiKey`: convenience for skills that declare `metadata.openclaw.primaryEnv`.\n* `config`: optional bag for custom per-skill fields; custom keys must live here.\n* `allowBundled`: optional allowlist for **bundled** skills only. If set, only\n  bundled skills in the list are eligible (managed/workspace skills unaffected).\n\n## Environment injection (per agent run)\n\nWhen an agent run starts, OpenClaw:\n\n1. Reads skill metadata.\n2. Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to\n   `process.env`.\n3. Builds the system prompt with **eligible** skills.\n4. Restores the original environment after the run ends.\n\nThis is **scoped to the agent run**, not a global shell environment.\n\n## Session snapshot (performance)\n\nOpenClaw 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.\n\nSkills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears (see below). Think of this as a **hot reload**: the refreshed list is picked up on the next agent turn.\n\n## Remote macOS nodes (Linux gateway)\n\nIf the Gateway is running 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 `nodes` tool (typically `nodes.run`).\n\nThis relies on the node reporting its command support and on a bin probe via `system.run`. If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects.\n\n## Skills watcher (auto-refresh)\n\nBy default, OpenClaw watches skill folders and bumps the skills snapshot when `SKILL.md` files change. Configure this under `skills.load`:",
      "language": "unknown"
    },
    {
      "code": "## Token impact (skills list)\n\nWhen 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:\n\n* **Base overhead (only when ≥1 skill):** 195 characters.\n* **Per skill:** 97 characters + the length of the XML-escaped `<name>`, `<description>`, and `<location>` values.\n\nFormula (characters):",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Locations and precedence",
      "id": "locations-and-precedence"
    },
    {
      "level": "h2",
      "text": "Per-agent vs shared skills",
      "id": "per-agent-vs-shared-skills"
    },
    {
      "level": "h2",
      "text": "Plugins + skills",
      "id": "plugins-+-skills"
    },
    {
      "level": "h2",
      "text": "ClawHub (install + sync)",
      "id": "clawhub-(install-+-sync)"
    },
    {
      "level": "h2",
      "text": "Security notes",
      "id": "security-notes"
    },
    {
      "level": "h2",
      "text": "Format (AgentSkills + Pi-compatible)",
      "id": "format-(agentskills-+-pi-compatible)"
    },
    {
      "level": "h2",
      "text": "Gating (load-time filters)",
      "id": "gating-(load-time-filters)"
    },
    {
      "level": "h2",
      "text": "Config overrides (`~/.openclaw/openclaw.json`)",
      "id": "config-overrides-(`~/.openclaw/openclaw.json`)"
    },
    {
      "level": "h2",
      "text": "Environment injection (per agent run)",
      "id": "environment-injection-(per-agent-run)"
    },
    {
      "level": "h2",
      "text": "Session snapshot (performance)",
      "id": "session-snapshot-(performance)"
    },
    {
      "level": "h2",
      "text": "Remote macOS nodes (Linux gateway)",
      "id": "remote-macos-nodes-(linux-gateway)"
    },
    {
      "level": "h2",
      "text": "Skills watcher (auto-refresh)",
      "id": "skills-watcher-(auto-refresh)"
    },
    {
      "level": "h2",
      "text": "Token impact (skills list)",
      "id": "token-impact-(skills-list)"
    },
    {
      "level": "h2",
      "text": "Managed skills lifecycle",
      "id": "managed-skills-lifecycle"
    },
    {
      "level": "h2",
      "text": "Config reference",
      "id": "config-reference"
    },
    {
      "level": "h2",
      "text": "Looking for more skills?",
      "id": "looking-for-more-skills?"
    }
  ],
  "url": "llms-txt#skills-(openclaw)",
  "links": []
}