Understanding Skills: The Complete Guide

#What Are Skills?

Skills are OpenClaw's plugin system. Each skill is a SKILL.md file — a Markdown document with YAML frontmatter that teaches your agent how to perform a specific task. Skills are not traditional code plugins. They are structured instructions that extend the agent's capabilities by telling it what tools to use, how to format responses, and what workflows to follow.

Think of skills like job training documents for your agent. When you install a "weather reporter" skill, you are not installing weather-fetching code — you are giving your agent instructions on how to use its web search tool to find weather data and present it clearly.

#Skills vs SOUL.md

It is important to understand the difference between skills and SOUL.md:

#How Skills Work

#The Skill Loading Process

When the OpenClaw Gateway starts, it loads skills in this order:

1. 1
   Discover skills under every configured root

   OpenClaw discovers a skill whenever SKILL.md appears anywhere under a configured root, up to 6 levels deep. The roots run from your workspace skills/ folder at the top, through project and personal agent skills, the managed skills directory, Workshop skills and bundled skills, down to extra directories and plugin skills.

2. 2
   Resolve name collisions by source

   When the same skill name appears in multiple places, the highest source wins. The workspace skills/ folder is the highest root, so a skill you write there shadows an installed or bundled skill with the same name.

3. 3
   Filter on requirements

   OpenClaw loads bundled skills plus any local overrides, and filters them at load time based on environment, config, and binary presence. A skill whose metadata.openclaw.requires entries are unmet never reaches the prompt.

4. 4
   Compile the eligible skills into the prompt

   Eligible skills are compiled into a compact XML block and injected into the system prompt, at a published cost of about 97 characters plus the length of each skill's name, description and location.

5. 5
   Refresh on change

   OpenClaw watches SKILL.md files under skills roots by default, and the refreshed list is picked up on the next agent turn in the same session.

#Skill Anatomy

Every SKILL.md file has two parts: frontmatter (YAML metadata) and body (Markdown instructions).

---
name: hacker-news-digest
description: Summarize the top Hacker News stories when the user asks for tech news or an HN digest.
homepage: https://github.com/<your-handle>/hacker-news-digest
metadata:
  openclaw:
    requires:
      bins:
        - curl
    emoji: "📰"
---
# Hacker News Digest
When the user asks for tech news or Hacker News updates, fetch the
current front page of Hacker News and summarize it.
## What to Include
- Top 10 stories with titles and point counts
- Brief one-sentence summary of each story
- Link to the discussion thread
## Formatting
Present results in a numbered list with bold titles. Include the
point count in parentheses after each title.
## Scheduled Mode
When a cron job or heartbeat asks for the digest, only report stories
with 200+ points to keep it focused.

#Frontmatter Fields Explained

Two fields are required. Everything else, including the whole metadata.openclaw block, is optional.

Building Custom Skills walks the full field list, including the metadata.openclaw keys this table summarizes.

#Browsing ClawHub

ClawHub is "the public registry for OpenClaw skills and plugins", and it lives at clawhub.ai. Browse it in a browser, from openclaw skills search, or from the standalone clawhub CLI.

#Via the Web

Open a skill's page before you install it. The ClawHub overview says the registry "tracks semver versions, tags such as latest, changelogs, files, downloads, stars, and security scan summaries", and that "Public pages show current registry state so users can inspect a skill or plugin before installing it." The ClawHub quickstart names the same fields as the pre-install check: "metadata, source links, versions, changelogs, and scan status".

A listing's scan state is the trust signal the docs actually describe: "Public listings show the latest scan state. Releases that are held or blocked by moderation may be hidden from search and install surfaces until resolved." Badge words are not a signal, because publishers cannot assign them as topics. ClawHub's publishing page lists approved, audited, certified, clawhub, community, curated, endorsed, featured, official, officials, openclaw, recommended, staff-pick, trusted, trusted-publisher and verified as topic names "reserved by ClawHub and are rejected", normalized before the check, "so Official and staff pick are rejected too." The one publisher distinction the skills CLI page does draw is narrow and governs installs and updates: "Community ClawHub skill installs and updates check trust before downloading", and "Official ClawHub skill publishers and bundled OpenClaw skill sources bypass this release-trust check."

Read the SKILL.md on the listing yourself, whatever the page says around it, which is what the skills reference asks for: "Treat third-party skills as untrusted code. Read them before enabling."

#Via the CLI

Search for skills from your terminal:

The skills CLI page prints no sample of the result table, and what it does document about the output is narrow: "Search results add v only to numeric version labels, preserving existing prefixes and build names", while "JSON output keeps the registry's original version values." For the fields themselves, the ClawHub CLI page says its own search "Output includes the skill slug, owner handle, display name, and relevance score", and warns that "Popularity is a small ranking prior, not a guarantee of top placement." No documented page shows a star score or a badge column in search output, so a screenshot carrying one is not describing either CLI.

There is no openclaw skills browse subcommand. search covers browsing too: the skills CLI page documents its query as "Optional query; omit it to browse the ClawHub Trending skills feed", and --limit <n> "Caps returned results."

Browse the Trending feed:

Cap the results, or take the machine-readable form:

To list the registry itself rather than the Trending feed, install the standalone ClawHub CLI and use explore. Its page says the command "Lists newest skills via /api/v1/skills?limit=...&sort=createdAt", that --limit <n> runs "1-200, default: 25", and that the sort flag is --sort newest|updated|rating|downloads|trending with newest as the default. Each result line carries the owner handle and slug, the version, an age and a summary, the "summary truncated to 50 chars". ClawHub's star and unstar commands are bookmarks rather than scores: they add or remove "a skill from your Bookmarks".

npm i -g clawhub
clawhub explore --sort downloads --limit 25
clawhub explore --sort trending --json

#Skill Categories on ClawHub

Categories are a closed list, not free text. ClawHub's publishing page says "Categories place a skill in the category filters on the ClawHub skills browse page", that "Topics become the filter chips offered inside a selected category", and that categories "must be slugs from this list, matched exactly, so Development is rejected." The list below is that table, carried over unchanged.

The same page caps the metadata: "A skill can carry at most 3 categories and at most 5 topics." It also explains why the Other category is worth opening rather than skipping, since "A skill first published without --categories is stored as other, so it only appears under the Other category".

#Installing Skills

#Install from ClawHub

By default this "installs into the active workspace skills/ directory", which is ~/.openclaw/workspace/skills/hacker-news-digest/. Add --global to target "the shared managed skills directory", ~/.openclaw/skills, which the skills reference describes as "visible to all local agents unless agent allowlists narrow it."

#Install a Specific Version

#Check a Skill Before Installing

There is no openclaw skills preview subcommand. What the documentation gives you before an install is ClawHub's verification envelope:

verify "Prints ClawHub's clawhub.skill.verify.v1 JSON envelope by default", and --card "Prints the generated Skill Card Markdown instead of JSON", exiting non-zero when ClawHub returns a failing decision. Read the SKILL.md source on the skill's clawhub.ai listing alongside it, because the skills reference is blunt about the risk: "Treat third-party skills as untrusted code. Read them before enabling." Check for:

• Instructions that go beyond what the description admits (see the Skill Security Audit Guide)
• Environment variables the body uses but the frontmatter never declares
• Steps that reach outside the skill's stated job

#Install from a Local Directory

--local is not a documented flag, and the argument is a directory rather than a file. Pass the folder, and use --as to override the slug:

#Install from a Git Repository

--git is not documented either. Git sources use a git: ref, optionally pinned to a branch or tag:

Both forms "expect SKILL.md at the source root", and the install slug "comes from SKILL.md frontmatter name when it is valid, then the source directory or repository name".

#Managing Installed Skills

#List All Skills

list is the "Default action when no subcommand is provided", so bare openclaw skills prints the same table. Three flags narrow it: --eligible lists only eligible skills (shown in the commands block; the page does not describe it further), --verbose expands it, and with --json "the machine-readable payload stays on stdout for pipes and scripts". list, info and check "request the selected Gateway's authoritative skill inventory" rather than reading a folder directly.

To find out why a skill is missing rather than just that it is missing:

check "reports missing prerequisites independently of agent exclusion", so a skill lacking a binary or an environment variable appears under Missing requirements instead of silently vanishing. For one skill's details, openclaw skills info <name> "resolves an exact skill name before a metadata key."

#Enable or Disable a Skill

There are no openclaw skills enable or openclaw skills disable subcommands. Disabling is a config change, under skills.entries.<name>.enabled in openclaw.json, which the skills reference describes as "false disables the skill even when bundled or installed."

{
  skills: {
    entries: {
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

The skill names in that snippet are the ones the skills reference uses in its own example. Set an entry back to true to re-enable it, and the watcher picks the change up on the next agent turn.

#Update a Skill

Update every tracked ClawHub install:

#Remove a Skill

Removal belongs to the standalone ClawHub CLI, not to openclaw skills. The skills CLI page says to "Use the standalone ClawHub CLI to remove a ClawHub-tracked skill", and to install it explicitly first if it is missing:

npm i -g clawhub
clawhub uninstall @owner/hacker-news-digest

The CLI "asks for confirmation before deleting the skill directory and its .clawhub/lock.json entry." Point --workdir at the same root the skill was installed into: the agent workspace for a workspace install, or the state directory for one installed with --global.

clawhub --workdir ~/.openclaw uninstall @owner/hacker-news-digest

The watcher "picks up the removal on the next agent turn. If watching is disabled, start a new session."

#Skill Precedence and Priority

When the same skill name appears in more than one place, OpenClaw resolves the collision by source, not by a frontmatter field. The skills reference publishes the full order and states the rule: "When the same skill name appears in multiple places, the highest source wins."

#Precedence Order

There is no numeric priority field in the frontmatter, and no custom subfolder anywhere in that list. A skill you author under ~/.openclaw/workspace/skills/ sits at the top of the table, which is exactly what lets it override a managed or bundled skill with the same name.

#Example: Conflicting Weather Skills

If a managed install and your own workspace folder both define weather-reporter, the workspace copy is the one that loads. The managed copy stays on disk; it is shadowed, not deleted. To keep both, rename one of them, and keep the folder name and the frontmatter name aligned, which is what the creating-skills naming rules ask for.

#How a Skill Gets Selected

There is no trigger list. The skills reference describes the per-run sequence: OpenClaw resolves the eligible skill list, injects configured env and API keys, and then "Eligible skills are compiled into a compact XML block and injected into the system prompt." The model sees each eligible skill's name, description and location, and reads the full SKILL.md only after it picks one, so the description is the text it matches against.

Two documented keys take that choice away from the model:

• disable-model-invocation: true keeps a skill 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".
• command-dispatch: tool routes the slash command straight to a registered tool, with no model involvement.

Gating runs before any of this: OpenClaw "filters them at load time based on environment, config, and binary presence", so a skill whose requires.env variable is unset never reaches the prompt. Every eligible skill is offered on every turn, which is why the skills reference tells authors to "Keep descriptions short and descriptive to minimize prompt overhead."

#Skill Interaction with the Agent

Skills do not run as separate processes. They modify the agent's behavior by adding instructions to the system prompt. When the agent receives your message:

1. The SOUL.md is loaded (personality)
2. Eligible skills are compiled into the system prompt, and the model picks one by description
3. The combined instructions form the agent's system prompt
4. The LLM processes your message with these instructions
5. The agent follows the skill's instructions to respond

This means a skill is only as reliable as the model's ability to follow the instructions in it, and that every extra eligible skill costs prompt space. The skills reference puts a number on the second half: "The cost is deterministic and scales linearly per skill", a base block whenever at least one skill is eligible plus, for each skill, "~97 characters + your name, description, and location field lengths". It converts that for you as well: "At ~4 chars/token, 97 chars ≈ 24 tokens per skill before field lengths."

#What ships with OpenClaw?

Bundled skills, and no docs page publishes the full list. OpenClaw's docs call the skills that arrive with an install bundled rather than built-in, and say only that "OpenClaw loads bundled skills plus any local overrides" and that bundled skills sit at priority 6 of the loading order, "shipped with the install". Individual names do surface in examples (coding-agent, the gemini and peekaboo entries in the bundled allowlist, and the skill behind the line "OpenClaw bundles a 1password skill"), but no page enumerates the set, so a tutorial that prints eight or ten built-in skill names is describing an inventory the documentation does not have.

One shipped library is enumerated, and only one agent ever loads it. "Custodian skills are release-versioned operational playbooks shipped with OpenClaw", and they "load at the bundled-skill precedence tier, but only for the agent resolved by agents.defaults.systemAgent.agentId." Their first wave is four skills, configure-channel, add-model-provider, diagnose-gateway and cloud-image-bake. The same page sketches later tiers and then disclaims them: "These names are roadmap entries, not bundled skills or promises of current behavior."

Read the list off your own install instead:

The skills CLI page says list, info and check "request the selected Gateway's authoritative skill inventory", so what comes back is what your Gateway actually loaded, bundled skills included. openclaw skills info <name> "resolves an exact skill name before a metadata key" for one skill's details.

The skills reference names one bundled skill, and it does so to flag an exception: "The coding-agent bundled skill is opt-in", enabled with skills.entries.coding-agent.enabled: true plus one of the supported coding CLIs installed and authenticated.

Bundled skills are configured rather than deleted. skills.entries.<name>.enabled set to false "disables the skill even when bundled or installed", and a second key narrows the bundled set alone. The skills config page describes skills.allowBundled as an "Optional allowlist for bundled skills only. When set, only bundled skills in the list are eligible. Managed, agent-level, and workspace skills are unaffected."

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
  },
}

That snippet is the docs' own example; substitute whatever openclaw skills list reports on your install. When a skill then goes missing, openclaw skills check says which mechanism removed it, because "Disabled skills and skills blocked by the bundled allowlist keep their separate readiness categories."

#Next Steps

• Building Custom Skills — Create your own skills
• Skill Security Audit — Review skills before installing
• SOUL.md Mastery — Shape your agent's personality
• Cost Optimization — Skills affect API usage