How to create an OpenClaw skill

Skills teach the agent how and when to use tools. Each one is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions, loaded from several roots in a defined precedence order, the workspace skills folder first. Here is the first skill in four steps, the reference for the frontmatter, conditional activation and key wiring, the personal-skill route on a shared Gateway, the Workshop proposal path for skills that should be reviewed, publishing, and the best practices the docs close with.

Your first skill

• Create the directory under the workspace skills folder; subfolders are fine for organisation, since the skill is named by its frontmatter, not the folder path.
• Write SKILL.md: a name in lowercase letters, digits and hyphens, aligned with the directory name, and a one-line description under 160 characters that the agent sees and that slash-command discovery shows; the body is the instruction, for example which tool to run and how.
• Verify it loaded with the skills list command; the watcher picks up new files by default, and an existing session needs a new session or a Gateway restart to see the refreshed list.
• Test it from the CLI with a one-message agent run, from chat by asking, or explicitly with the skill command and its name.

Skills teach the agent how and when to use tools.

The reference

Two required fields, name and description. Optional keys: user-invocable, true by default, exposes the skill as a slash command; disable-model-invocation keeps it out of the system prompt while still runnable by command; command-dispatch set to tool routes the command straight to a named tool, bypassing the model, with a raw argument mode; and a homepage URL. A base-directory placeholder references files inside the skill without hardcoding paths. Conditional activation lives in the metadata: all of a list of binaries must exist, or at least one of another list, environment variables must exist in the process or config, config paths must be truthy, an OS filter, and an always flag that includes the skill on a compatible OS even when the checks fail. An API key is wired to the skill entry in the config, sourced from the environment, and injected into the host process for that agent turn only; it does not reach the sandbox.

Personal skills, proposals, publishing

• For a skill that should follow your signed-in profile rather than an agent workspace on a shared Gateway, the plugins page has a personal skills section where you create or import the bundle and review the saved revision, with no host shell access needed; the agent can also draft one through its Workshop tool, which reports whether the result is published or a pending proposal.
• For agent-drafted skills or when an operator should review before a skill goes live, the Workshop CLI proposes a new skill or an update from a proposal file, or a proposal directory with support files under assets, examples, references, scripts or templates, and after review you inspect, evaluate and apply.
• Publishing to ClawHub needs a publisher handle, personal or an organisation where you hold a publishing role, the standalone ClawHub CLI installed and logged in, and one publish command pointed at the skill directory, with flags to override the inferred version or the owner.

OpenClaw skills explained explains how skills load and gate once they exist, and OpenClaw self-learning how the agent writes its own.

Best practices

Four lines from the docs: be concise and instruct the model on what to do, not how to be an AI; safety first, so a skill that uses exec must not let untrusted input inject arbitrary commands; test locally with a one-message run before sharing; and browse the community registry before building from scratch. What is ClawHub explains the registry, and The best OpenClaw skills the skills worth installing before writing one.

On Diali

On Diali the catalog installs a skill in one click and a SKILL.md of your own goes in the same workspace folder; the credentials a skill needs are set per skill from the dashboard rather than in the config file. Hosted OpenClaw on Diali is the assistant.

• A directory, a SKILL.md, a name and a description.
• Gate on binaries, env and OS; keys never reach the sandbox.
• Propose through Workshop when someone should review first.