On this page
On this page
CLI commands
Skills CLI
openclaw skills
Inspect local skills, search ClawHub, install skills from ClawHub/Git/local directories, verify ClawHub skills, and update ClawHub-tracked installs.
Use openclaw plugins for plugin packages. The standalone
ClawHub CLI handles publishing, registry
maintenance, and removing ClawHub skills.
Related:
- Skills system: Skills
- Skill authoring: Creating skills
- Skill Workshop: Skill Workshop
- Skills config: Skills config
Commands
search, update, and verify use ClawHub directly. install @owner/<slug>
installs a native ClawHub skill. install skills-sh:<owner>/<repo>/<slug> asks
ClawHub to resolve an external listing to its exact synchronized GitHub commit;
OpenClaw does not download from skills.sh. These entries are shown as
Not scanned by ClawHub, and that trust state is preserved through updates
and verification. Claimed or ClawHub-scanned skills use @owner/<slug>.
install git:owner/repo[@ref] clones an unmanaged Git skill, and install ./path copies a local skill directory. Both fail before copying when the root
SKILL.md is not loadable under the same content rules: frontmatter with a
description, within skills.limits.maxSkillFileBytes. A hardlinked source file
is copied as a new file, so that link does not fail the check. By default, install,
update, and verify target the active workspace skills/ directory; with
--global, they target the shared managed skills directory. list/info/check
and bare openclaw skills request the selected Gateway's authoritative skill
inventory. A configured remote Gateway or an explicit OPENCLAW_GATEWAY_URL
never falls back to client-local skills: missing URLs, connection failures, and
authentication errors remain visible. Only an implicitly selected local Gateway
can fall back to local inventory when it is unavailable. Workspace-backed
commands resolve the target workspace from --agent <id>, then the current
working directory when it is inside a configured agent workspace, then the
default agent.
Search results add v only to numeric version labels, preserving existing prefixes
and build names. JSON output keeps the registry's original version values.
The skills table renders horizontal tabs as single spaces so descriptions stay aligned with the neighboring columns. JSON output preserves tabs and line endings in descriptions and paths as escaped characters.
info resolves an exact skill name before a metadata key. Key, case-insensitive,
and separator-normalized matches must identify one skill; ambiguous selectors
fail instead of choosing discovery order.
check separates inventory, readiness, and visibility:
- Inventory means OpenClaw found the skill in a configured root or bundled source and can report its status.
- Readiness means the skill's declared prerequisites are satisfied for the selected Gateway or node, so it is eligible to run.
- Visibility means an eligible skill is exposed to the selected agent's prompt, picker, or command surface after agent filters and invocation flags are applied.
check reports missing prerequisites independently of agent exclusion: a skill
excluded by the agent allowlist can also appear under Missing requirements.
Disabled skills and skills blocked by the bundled allowlist keep their separate
readiness categories. Treat a listed skill with missing requirements as present
in inventory but not currently eligible or visible to the agent; install or
configure the reported prerequisite before expecting the model to use it
successfully.
Workshop commands preserve the same target boundary. They never read or mutate client-local state after an explicitly selected Gateway fails; intentional offline behavior remains available only for an implicitly selected local Gateway.
Git and local directory installs expect SKILL.md at the source root. The
install slug comes from SKILL.md frontmatter name when it is valid, then
the source directory or repository name; use --as <slug> to override it.
--version is ClawHub-only. Skill installs do not support npm package specs
or zip/archive paths, and openclaw skills update updates ClawHub-tracked
installs only.
Gateway-backed skill dependency installs triggered from onboarding or Skills
settings use the separate skills.install request path instead.
When security.installPolicy returns warn in an interactive terminal,
OpenClaw prints the reason and findings, then asks type: '<skill>' to install anyway (or update anyway). If the fully rendered review exceeds 4,000
characters, OpenClaw stops before prompting; reduce or coalesce the
policy output first. A matching answer evaluates the staged skill
again before continuing. Declined and non-interactive direct CLI commands stop
before commit; after review, --acknowledge-install-policy-warning is the
explicit noninteractive approval for every warning in that command invocation.
Every approved warning is re-evaluated before continuing. Automatic and managed
skill installs cannot use that flag themselves. Use an equivalent direct CLI
command when one exists; otherwise, change security.installPolicy to return
allow for the reviewed request, then retry the managed flow. Neither --force
nor the acknowledgement overrides block or a policy failure.
Notes:
| Flag/behavior | Description |
|---|---|
search [query...] |
Optional query; omit it to browse the ClawHub Trending skills feed. |
search --limit <n> |
Caps returned results. |
install git:owner/repo[@ref] |
Installs a Git skill. Branch refs may contain slashes, such as git:owner/repo@feature/foo. |
install ./path/to/skill |
Installs a local directory whose root contains SKILL.md. |
install --as <slug> |
Overrides the inferred slug for Git and local directory installs. |
install --version <version> |
Applies to native ClawHub skill refs, not skills-sh: refs; the mirrored reference already identifies the exact synchronized commit. |
install --force |
Overwrites an existing workspace skill folder for the same slug. |
update --force |
Replaces a tracked skill even when its installed files no longer match recorded install digests. Without it, updates preserve local changes. Pre-digest installs require one forced update before later updates can be verified. Force those skills individually; --all --force also replaces skills with detected local edits. |
install/update --force-install |
Installs a pending GitHub-backed ClawHub skill before ClawHub's scan completes. |
--global |
Targets the shared managed skills directory; cannot combine with --agent <id>. |
--agent <id> |
Targets one configured agent workspace; overrides current working directory inference. |
update @owner/<slug> |
Updates a single tracked skill. Add --global to target the shared managed skills directory instead of the workspace. |
update --all |
Updates tracked ClawHub installs in the selected workspace, or the shared managed skills directory with --global. |
verify @owner/<slug> |
Prints ClawHub's clawhub.skill.verify.v1 JSON envelope by default. --json is accepted as the explicit machine-output spelling. Bare slugs are accepted for compatibility when the skill is already installed or unambiguous; owner-qualified refs avoid publisher ambiguity. |
verify provenance |
When ClawHub returns server-resolved source provenance, verify JSON also includes a commit-pinned openclaw.verifiedSourceUrl. Unavailable or self-declared source URLs stay only in the raw provenance envelope and are not promoted. |
verify version selector |
verify uses .clawhub/origin.json for installed ClawHub skills, so it verifies the installed version against the registry it came from. --version and --tag override the version selector but keep that installed registry when origin metadata exists. |
verify --card |
Prints the generated Skill Card Markdown instead of JSON. Exits non-zero when ClawHub returns ok: false or decision: "fail". |
| Skill Card fingerprint | Installed ClawHub bundles can include a generated skill-card.md. OpenClaw treats verification as a ClawHub server decision and does not reject an installed skill just because that generated card changes the bundle fingerprint. |
check --agent <id> |
Checks the selected agent's workspace and reports which ready skills are actually visible to that agent's prompt or command surface. |
workshop --agent <id> |
Accepted before or after a Workshop leaf command, for example workshop --agent <id> list or workshop list --agent <id>. If both are provided, the leaf value wins. |
list |
Default action when no subcommand is provided. |
list/info/check output |
Rendered output goes to stdout. With --json, the machine-readable payload stays on stdout for pipes and scripts. |
On servers supporting full scanner reports, verification JSON includes security.scannerReports.aig (the full upstream SARIF report)
and security.scannerReports.skillspector (the full upstream JSON report) when ClawHub
has retained them. Nested scanner fields pass through unchanged, including
coverage and incomplete-analysis details. A report is null when unavailable,
including older scans whose full output was not retained; summaries are not
substituted. Older servers may omit security.scannerReports entirely. verify
reads the stored scan and does not start another scan. Verification responses
can be up to 64 MiB; larger responses fail explicitly without printing partial
reports. Other ClawHub JSON requests retain their 16 MiB limit.
Release trust
Community ClawHub skill installs and updates check trust before downloading.
Versioned community archive releases use exact-release trust metadata.
Resolver-backed GitHub skills rely on ClawHub's install resolver to enforce
scan and force-install policy before it returns a pinned commit; use
--force-install to install a pending GitHub-backed skill before that scan
completes. Malicious or blocked community releases are refused. Review
outcomes print the exact ClawHub audit overview and details link, then continue.
Official ClawHub skill publishers and bundled OpenClaw skill sources bypass
this release-trust check.
Remove a ClawHub skill
Use the standalone ClawHub CLI to remove a ClawHub-tracked skill. If the CLI is not installed, install it explicitly first:
The CLI asks for confirmation before deleting the skill directory and its
.clawhub/lock.json entry. Use the installed skill's owner-qualified name or
bare slug, not its original skills-sh: reference.
Select the same root where the skill was installed: the agent workspace for an
agent-specific skill, or the OpenClaw state directory for a shared skill
installed with --global:
If OPENCLAW_STATE_DIR is set, use that configured state directory for shared
skills instead:
The default skills watcher picks up the removal on the next agent turn. If watching is disabled, start a new session.
Personal skill library
openclaw skills library manages the identified caller's skills on the selected
Gateway. It uses the same owner-aware service as the Control UI and agent
workflow; it never writes the library database or revision directories on the
CLI host.
List your library:
Create a private skill from a directory containing SKILL.md:
Read its stable ID and current revision before editing:
Update only the instructions while preserving supporting files:
A directory input replaces the complete bundle. A single SKILL.md input
preserves the current supporting files; repeat --delete-file <relative-path>
to remove files explicitly. Updates compare the revision that was read; a
conflict requires reviewing the newer content, not a force overwrite.
Supporting files are part of the revision, including binary assets and
executable flags.
Import a ZIP privately:
Import a ClawHub skill without publishing your library:
--version <version> selects a ClawHub version and requires --clawhub.
share, unshare, transfer, enable, disable, remove, and rollback
take <skill-id> --expected-revision <hash>. Rollback also requires
--revision <retained-hash>.
Attach an exact revision to an existing session:
detach takes the same session and skill ID. Refresh one selected skill:
Omitting --skill-id refreshes all selected skills and requires current library
access to each one. It never replaces the selection with the current caller's
library. Each operation reports its effect on the next turn.
Use list --session <session-key> to inspect selected revisions and the skills
you can attach, without changing the session. read --session <session-key>
also requires --revision <hash> and reads only that exact selected revision;
it does not expose other private revisions or grant permission to edit them.
Personal operations require an authenticated Gateway profile. The Control UI on a single-user Gateway uses a durable owner profile, but ephemeral CLI connections do not inherit it. A CLI shared token or password alone still has no personal profile; use the existing workspace commands in that case. An explicitly selected remote Gateway never falls back to a client-local personal library.
Sharing makes a skill available to teammates but does not grant edit access. Transfer to team ownership requires administrator authority. Saving affects new sessions by default; attach or refresh a selection explicitly for an existing session. Removal preserves already selected revisions. See personal library ownership and revisions.
Skill Workshop
openclaw skills workshop inspects and manages the learned (Workshop) skills
of the selected agent. Agents create and update these skills themselves; every
change applies immediately and saves the previous version first. See
Skill Workshop.
| Command | Description |
|---|---|
list |
Lists live learned skills with usage counts, plus archived skills. Shows the autonomous mode and skills root. |
changes [--limit <n>] |
Shows recent changes, newest first: who made them (agent, review, curator, user), the action, and the saved version id. |
show <name> [--file <path>] [--version <id>] |
Prints SKILL.md or one support file, from the live skill or a saved version. |
archive <name> [--reason <text>] |
Hides the skill from its agent. The skill stays restorable. |
restore <name> [--version <id>] |
Restores the newest saved version, or the named one. The current live copy is saved first, so restore is undoable. |
Every Workshop command accepts --agent <id> and --json. archive and
restore act as user in the change feed.
