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 source workspace as the skill source. That source is read and watched on the Gateway, even when a File Transfer plugin serves the agent workspace from a paired node. The node reads its configured agent skill roots; it does not receive Gateway source paths. Selected skill files and supporting resources are delivered from their owning host. Model-facing workspace-hosted entries use workspace-skill:// read locations, so an identical Gateway path cannot redirect the read to the node. The configured agent workspace remains the primary skill source even when the session executes in a worktree; only selecting that worktree as the agent's workspace gives its skills primary precedence. 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.

Each discovery pass reports one summary per winning/losing discovery root and source kind, with the skill count and up to three example names. Workspace or project skills overriding bundled skills, and managed-worktree skills overriding project checkout skills, are warnings; other collisions are informational. Worktree provenance uses the configured worktreeRoot (the state directory's worktrees/ by default), without checking Git. Identical content stays silent. Unchanged root-pair summaries are not repeated on refresh; changes to content, declared metadata, or collision membership update the summary. Precedence is unchanged.

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 stable 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 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 Gateway 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: {    ownership: "explicit",    defaults: {      skills: ["github", "weather"], // shared baseline      heartbeat: { agentId: "writer" },      systemAgent: { agentId: "writer" },      authInheritance: { agentId: "writer" },    },    entries: {      writer: { workspace: "~/.openclaw/workspace" }, // inherits github, weather      docs: { skills: ["docs-search"] }, // replaces defaults entirely      "locked-down": { skills: [] }, // no skills    },  },  talk: { agentId: "writer" },}

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 lets an agent save and update its own skills in <state-dir>/agents/<agentId>/agent/workshop-skills. Every change applies immediately, is announced, and saves the previous version so it can be undone. Learned skills are always visible to their agent; archive one to hide it. Operators edit skills outside that directory through their owning tools or files.

openclaw skills workshop listopenclaw skills workshop changesopenclaw skills workshop archive <name>openclaw skills workshop restore <name>

See Skill Workshop for how agents learn skills and openclaw skills workshop for the CLI reference.

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.

Skill inventory, skill readiness, and skill visibility are related but different:

• Inventory answers whether OpenClaw discovered the skill in a configured root or bundled source.
• Readiness answers whether the current runtime can satisfy the skill's declared requirements, such as binaries, environment variables, config paths, operating system constraints, or reachable node-hosted capabilities.
• Visibility answers whether a ready, eligible skill is exposed to the selected agent after agent allowlists, invocation flags, and session snapshot rules are applied.

A skill can be present in inventory but still not ready or visible. Use openclaw skills check when debugging a skill that appears in configuration but does not show up for an agent, or when its required tool, credential, or host capability is missing.

---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. New sessions recheck skill prerequisites, including binaries installed into an existing PATH directory, even when the skill files have not changed. Existing snapshots keep their selected skill sources: a newly eligible skill with the same name does not replace another source's implementation during hydration.

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.
• A previously idle or evicted workspace resumes watching on its next agent turn.

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.

When native events are unavailable, skills polling runs every 30 seconds by default. A valid CHOKIDAR_INTERVAL overrides this default for automatic fallback and explicitly requested polling, with a 20 ms minimum. Shorter intervals increase background scanning cost, especially for large skill trees. Native event hints still trigger prompt refreshes with the normal debounce. Each watcher logs one warning when automatic selection falls back to polling, including the reported reason when available.

Watcher subscriptions are retained for the 128 most recently used combinations of agent, configured workspace, and execution workspace. Subscriptions idle for an hour are also retired when another workspace prepares its skills. Shared skill roots remain watched while a retained subscription needs them. The next watching turn reacquires retired roots and refreshes file-backed skills before using them; managed library revisions remain pinned. This bounds retained subscriptions, not the total number of operating-system file watches.

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

Search installed skills

The prompt contains a bounded skill directory. Skills omitted by the prompt budget remain discoverable through skills_search when that tool is enabled. Small catalogs continue to appear in full.

When search is available, the agent is instructed to check for a relevant skill before work involving files, specialized tools, or a reusable workflow. An omitted directory is identified explicitly; the agent searches by task goal instead of trying to scan a list that is not present. Known names and clear directory matches can go directly to a complete skill read. Simple conversation and self-contained answers do not require discovery.

• skills_search({ query, limit? }) searches eligible installed names, descriptions, and bounded instruction text. The default limit is 5; the maximum is 20. Queries must contain 1-1,000 characters. Results contain names, locations, and shortened descriptions, not instructions. hasMore indicates that additional matches exist.
• skills_read({ name }) loads the complete SKILL.md for an exact name. Search is not required when the name is already known. Instructions omitted from the prompt directory are limited to 256 KiB and rejected if larger, not truncated. Prompt-listed instructions retain the existing whole-read contract, including Code Mode's separate program-data limits.

Both tools use the current session's eligible catalog. Disabled, filtered, ineligible, and model-hidden skills are not added by search. Existing explicit user references remain separate. Search does not query ClawHub, install a skill, or grant permission to execute its commands.

Instruction-body indexing requires the effective native skills_read tool. When reads are denied or shadowed, search uses metadata only and performs no instruction-body reads. Revocation also excludes cached body matches and rejects in-flight indexing started under the previous grant.

In OpenClaw Code Mode, use await skills.search(query, limit) and await skills.read(name). These calls dispatch through the same tools and policies. await skills.list(offset) returns up to 20 directory entries; the default offset is 0. Codex receives the OpenClaw tools through its dynamic tool surface; these are distinct from Codex's native skill-resource tools. Codex refuses a skill read that exceeds the turn's dynamic-tool output budget instead of returning partial instructions as a successful read. An existing read policy grant also permits skills_read. An explicit skills_read denial still wins; search permission alone does not grant reads.

Search uses an in-memory lexical index of the prepared catalog. It follows the existing snapshot and refresh rules, with no embedding service or persistent search index. The first search reads bodies through the admitted filesystem owner. Concurrent first searches share one build; cancelling a waiter does not cancel its owner. Later searches reuse the completed index for that prepared catalog and still check current run authority. Names and descriptions have twice the lexical weight of body text; exact names rank first.

Body indexing reads at most 1,024 skills in name order, four at a time. Each body contributes at most 16 KiB, reduced equally across the selected skills to keep their total at most 4 MiB. Local files contribute a bounded prefix, with one extra byte read to detect truncation. Owners that reject oversized bounded reads or do not support bounded search reads retain metadata only. Remote workspace owners with whole-skill reads only do not use their document bridge for indexing. Already-delivered inline bodies can contribute a bounded prefix. Metadata remains searchable for the full eligible catalog. If bodies are unreadable, omitted, or shortened, coverage reports bodyIndexed, metadataOnly, and truncatedBodies. An empty result with partial coverage does not prove that no applicable skill exists. Indexing never executes skill content, and index limits do not truncate skills_read.

Sandbox search includes only readable, delivered skills. Discovery does not expand the existing worker transfer selection or its 8 MiB total resource limit. Dedicated remote workers retain their existing tool protocol; the new search tools are not added to that protocol. Use a Gateway run to search its full eligible catalog.

Token impact

When skills are eligible, OpenClaw injects a compact XML block into the system prompt. The cost follows a fixed formula 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