Skills

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

File-backed skills load from these sources, highest precedence first. When the same skill name appears in multiple places, the highest source wins. Personal library skills are selected by identity and revision rather than discovered by scanning every user's files.

When a session uses a different execution workspace, OpenClaw also loads that workspace's skills/ and .agents/skills/ directories. These skills follow the entire agent catalog in precedence and prompt order; within the execution workspace, skills/ wins over .agents/skills/. Both directories participate in snapshot refresh and sandbox synchronization. Sandboxed runs read the materialized copies, not the original host paths.

Managed worktree sessions keep their recorded canonical workspace as the skill source. A selected nested workspace stays nested: discovery does not walk up to its parent repository. Installing OpenClaw from a repository does not make that repository's .agents/skills/ a global bundled skill source.

Skill roots support grouped layouts. OpenClaw discovers a skill whenever SKILL.md appears anywhere under a configured root (up to 6 levels deep):

<workspace>/skills/research/SKILL.md          ✓ found as "research"<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"

During grouped discovery, finding SKILL.md ends traversal below that directory. Invalid skill files are reported and skipped; valid siblings can still load.

The folder path is for organization only. The skill's name and slash command come from the name frontmatter field (or the directory name when name is missing). Agent allowlists (below) also match on this name.

The release-versioned Custodian skill library shares the bundled precedence tier but is absent for every agent except the configured system/Custodian agent.

Node-hosted skills

A connected headless node can publish skills installed in its active OpenClaw skills directory (~/.openclaw/skills by default; profile environment overrides apply). They appear in the normal agent skill list while the node is connected and disappear when it disconnects. A local or Gateway skill keeps its name on collision; the node skill receives a deterministic node-prefixed name. Node-hosted v1 requires the directory name to match the skill's name frontmatter field. The published name, description, and instructions come from the same captured file content.

The skill entry includes the node locator. Its files, relative references, and binaries live on the node, so load and execute it with exec host=node node=<node-id>. Restart the node host after changing its skill files. See Nodes for pairing and off-switches.

Per-agent vs shared skills

In multi-agent setups, each agent has its own workspace. Use the path that matches your desired visibility:

Workshop skills learned by one agent are not shared with another agent. Publish a skill to the managed library when it must be available to multiple agents.

When OPENCLAW_STATE_DIR points somewhere other than the default ~/.openclaw, session skill indexes exclude home-scoped personal or compatibility skill roots such as ~/.agents/skills. Workspace, project, bundled, extra, and state-owned managed skills continue to load normally.

Personal skills on a shared Gateway

On a shared Gateway, identified operators can keep a personal skill library without receiving permission to change everybody's workspace skills or Gateway configuration. Open Plugins → Skills to create a skill, import a SKILL.md or ZIP bundle, or add a skill from ClawHub. The editor keeps supporting scripts, references, and assets with the instructions.

The ordinary single-admin setup stays unchanged: workspace authoring still uses <workspace>/skills, and existing file-backed skills are not moved into the library. A shared token does not identify a person. Personal library operations require an authenticated Gateway profile. The team-specific interface and agent guidance use distinct canonical Gateway profiles, not channel senders, contacts, accounts, agents, devices, or browser connections. Linked and merged login identities count as one profile.

Ownership and sharing

New managed skills belong to the authenticated creator. Share with team makes a skill available to other operators without giving them edit access. An administrator can transfer to team, changing management ownership while retaining the original author. Sharing and transfer do not move files or change the skill's stable ID. Profile merges retain existing revision paths.

Use the skill picker or returned command identity when invoking a managed skill. Different owners can use the same friendly name without one skill silently replacing another.

Revisions and session selection

Saving publishes a complete immutable revision: SKILL.md and every supporting file. The revision hash includes portable file paths, exact content, sizes, and executable flags. Editing only a helper script still changes the revision; sharing, ownership changes, ZIP timestamps, and archive entry order do not. Identical saves are no-ops. A stale edit fails with a conflict instead of overwriting a newer revision.

A session retains its selected skill IDs and revisions. Another person joining or taking ownership of the session does not replace that selection. Published changes are available to new sessions; explicitly attach or refresh a skill to use it on the next turn of an existing session. Rollback selects a retained revision. Removing a skill from the library excludes it from new selections without deleting a revision already selected by a session. Disabling a skill removes it from new-session defaults; explicit attachment remains available.

A new session selects up to 64 enabled library skills, with personal skills first and stable ID ordering within each group. If the library exceeds that limit, the Skills page explains how to detach a selected skill and attach another. Enablement does not bypass agent allowlists, required binaries, operating-system restrictions, or other prerequisites.

A managed bundle is limited to 256 files, 1 MiB per file, and 8 MiB total. Worker resource delivery also has an 8 MiB aggregate limit; narrow the session selection if its complete bundles exceed that limit. Published revisions are retained, including revisions still selected by older sessions.

ZIP imports allow up to 16 unfinished uploads per canonical profile and 32 across the Gateway. Linked or merged identities share the profile limit. Completed imports do not count toward either limit, and uploads expire one hour after they begin. If a profile merge or upgrade leaves more uploads than the limit allows, existing unexpired uploads can still be completed. Finish existing uploads or wait for them to expire before starting more.

The Gateway stores library records and revision metadata in state/openclaw.sqlite, and immutable bundles under skill-library/<skill-id>/revisions/<revision-hash>/ inside its state directory. Do not edit those managed directories directly. Use the editor, the Skills library CLI, or the agent's authorized authoring tool. Runtime copies are separate from project files and must not be committed with a project.

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    },    entries: {      writer: { default: true }, // inherits github, weather      docs: { skills: ["docs-search"] }, // replaces defaults entirely      "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 a plugin skill's own eligibility via metadata.openclaw.requires in its frontmatter, same as any other skill.

For multi-account channel plugins, gate general messaging skills on the channel subtree (for example, channels.discord), not a root token field: credentials may live under a named account. This is a coarse skill-visibility check. The plugin still owns credential resolution, account enablement, action availability, and authorization; an eligible skill does not grant tool access.

See Plugins and Tools for the full plugin system.

Reference a skill in a prompt

Type $ in the Control UI composer to search the skills available to the current agent. Selecting a result inserts its stable command name, for example $release_notes, without replacing the rest of your message. A prompt can reference more than one skill:

Use $github and $release_notes to summarize this change for the release.

OpenClaw resolves explicit references from authorized senders on every channel and on generic Gateway, CLI, and webhook agent turns. It matches the current agent's eligible, user-invocable skills and tells the model to read each referenced SKILL.md before acting. A single message can reference up to eight distinct skills; OpenClaw returns a visible error instead of ignoring extra or allowlist-hidden references. The $ form is composable prompt text. On channel messages, /release_notes ... remains the standalone command form and may use direct tool dispatch when the skill declares command-dispatch: tool; generic agent turns expand the same leading skill command as model instructions without running the channel command dispatcher. Common uppercase shell variables such as $HOME, $PATH, and $EDITOR remain ordinary text; use lowercase $home, $path, or $editor to reference skills with those names. Escape a reference as \$name when it should stay literal.

Skills with disable-model-invocation: true stay out of the $ picker and the model's normal prompt, so the model cannot select them on its own. An authorized explicit $skill-name reference still invokes them; the flag only hides the skill from model-initiated selection.

Skill Workshop

Skill Workshop is a proposal queue between the agent and its <state-dir>/agents/<agentId>/agent/workshop-skills directory. When the agent spots reusable work, it drafts a proposal instead of writing directly to SKILL.md. The scheduled weekly collection review is the scoped exception: its normal isolated turn may edit SKILL.md files directly inside the Workshop directory. Operators edit skills outside that directory through their owning tools or files.

openclaw skills workshop listopenclaw skills workshop inspect <proposal-id>openclaw skills workshop evaluate <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.

Security

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-labdescription: 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

Gating

OpenClaw filters skills at load time using metadata.openclaw (JSON5 object embedded in the frontmatter, see the parsing note above). A skill with no metadata.openclaw block is always eligible unless explicitly disabled.

---name: image-labdescription: Generate or edit images via a provider-backed image workflowmetadata:  {    "openclaw":      {        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },        "primaryEnv": "GEMINI_API_KEY",      },  }---

Fresh dependency checks detect binaries installed into directories already on PATH. This does not refresh an existing session's skill snapshot; see Snapshots and refresh.

Installer specs

Installer specs tell the macOS Skills UI how to install a dependency:

---name: geminidescription: 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:

For the bundled claude-cli backend, sessions without library selections materialize eligible skills as a temporary Claude Code plugin, passed via --plugin-dir. Sessions with library selections use OpenClaw's prompt catalog and pinned revision paths instead. OpenClaw omits --plugin-dir for those sessions to keep Claude's native skill aliases from conflicting with library command identities. Other CLI backends use the prompt catalog only.

Snapshots and refresh

OpenClaw snapshots eligible skills when a session starts and reuses that list until a refresh trigger below applies.

Managed library selections keep their exact revisions until an explicit attach or refresh, including across Gateway restarts. The refresh triggers below apply to ordinary file-backed skill roots.

File-backed skills refresh mid-session when:

• The skills watcher detects a SKILL.md change.
• The Gateway restarts, including when skills.load.watch is false.
• A new eligible remote node connects.
• Native file-watch capacity is exhausted and the next agent turn starts.

The refreshed list is picked up on the next agent turn in the same session. If the effective agent allowlist changes, OpenClaw refreshes the snapshot to keep visible skills aligned.

When native watch capacity is exhausted, OpenClaw logs one warning and stops the skills watchers. With watching enabled, later agent turns refresh file-backed skills through the existing snapshot preparation. Restart the Gateway after restoring watch capacity to enable native watching again.

{  skills: {    load: {      extraDirs: ["~/path/to/agent-scripts/skills"],      allowSymlinkTargets: ["~/path/to/skills"],      watch: true, // default    },  },}

Token impact

When skills are eligible, OpenClaw injects a compact XML block into the system prompt. The cost is deterministic and scales linearly per skill:

• Base overhead (only when 1+ skills are eligible): a fixed block of intro prose plus the <available_skills> wrapper.
• Per skill: ~97 characters + your name, description, and location field 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.

If the rendered block would exceed the configured prompt budget (skills.limits.maxSkillsPromptChars), OpenClaw first preserves as many skill identities (name and location) as the description-free compact format can fit. It then uses any remaining budget for shortened descriptions. If no description budget remains, descriptions are omitted. The prompt includes a note pointing at openclaw skills check whenever compact formatting or list truncation is required.

Keep descriptions short and descriptive to minimize prompt overhead.

For small context windows, the OpenClaw embedded runtime further shortens the descriptions in the already-admitted catalog. It retains every admitted name, location, and loading note, even when these exceed the description budget. Full skill instructions and saved snapshots are unchanged; Code Mode can still read every admitted skill. Native harnesses retain their own prompt policy.

Related