Skip to main content
Skills teach the agent how and when to use tools. Each skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. OpenClaw loads skills from several roots in a defined precedence order.

​
Create your first skill

1

Create the skill directory

Skills live in your workspace skills/ folder:
mkdir -p ~/.openclaw/workspace/skills/hello-world
You can group skills in subfolders for organization — the skill is still named by the SKILL.md frontmatter, not the folder path:
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world
2

Write SKILL.md

The frontmatter defines metadata; the body gives the agent instructions.
---
name: hello-world
description: A simple skill that prints a greeting.
---

# Hello World

When the user asks for a greeting, use the `exec` tool to run:

```bash
echo "Hello from your custom skill!"


Naming rules:
- Use lowercase letters, digits, and hyphens for `name`.
- Keep the directory name and frontmatter `name` aligned.
- `description` is shown to the agent and in slash-command discovery —
  keep it one line and under 160 characters.

</Step>

<Step title="Verify the skill loaded">
```bash
openclaw skills list
OpenClaw watches SKILL.md files under skills roots by default. If the watcher is disabled or you are continuing an existing session, start a new one so the agent receives the refreshed list:
# From chat — archive current session and start fresh
/new

# Or restart the gateway
openclaw gateway restart
3

Test it

openclaw agent --message "give me a greeting"
Or open a chat and ask the agent directly. Use /skill hello-world to invoke it explicitly by name.

​
SKILL.md reference

​
Required fields

FieldDescription
nameUnique slug using lowercase letters, digits, and hyphens
descriptionOne-line description shown to the agent and in discovery output

​
Optional frontmatter keys

FieldDefaultDescription
user-invocabletrueExpose the skill as a user slash command
disable-model-invocationfalseKeep the skill out of the agent’s system prompt (still runs via /skill)
command-dispatch—Set to tool to route the slash command directly to a tool, bypassing the model
command-tool—Tool name to invoke when command-dispatch: tool is set
command-arg-moderawFor tool dispatch, forwards the raw args string to the tool
homepage—URL shown as “Website” in the macOS Skills UI
For gating fields (requires.bins, requires.env, etc.) see Skills — Gating.

​
Using {baseDir}

Reference files inside the skill directory without hardcoding paths — the agent resolves {baseDir} against the skill’s own directory: 
Run the helper script at `{baseDir}/scripts/run.sh`.

​
Adding conditional activation

Gate your skill so it only loads when its dependencies are available: 
---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---
KeyDescription
requires.binsAll binaries must exist on PATH
requires.anyBinsAt least one binary must exist on PATH
requires.envEach env var must exist in the process or config
requires.configEach openclaw.json path must be truthy
osPlatform filter: ["darwin"], ["linux"], ["win32"]
alwaysSet true to skip all gates and always include the skill
Full reference: Skills — Gating.
Wire an API key to a skill entry in openclaw.json:
{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}
The key is injected into the host process for that agent turn only. It does not reach the sandbox — see sandboxed env vars.

​
Propose via Skill Workshop

For agent-drafted skills or when you want operator review before a skill goes live, use Skill Workshop proposals instead of writing SKILL.md directly. 
# Propose a brand-new skill
openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that prints a greeting." \
  --proposal ./PROPOSAL.md

# Propose an update to an existing skill
openclaw skills workshop propose-update hello-world \
  --proposal ./PROPOSAL.md \
  --description "Updated greeting skill"
Use --proposal-dir when the proposal includes support files: 
openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that prints a greeting." \
  --proposal-dir ./hello-world-proposal/
The directory must contain PROPOSAL.md at its root. Support files go under assets/, examples/, references/, scripts/, or templates/. After review: 
openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>
See Skill Workshop for the full proposal lifecycle.

​
Publishing to ClawHub

1

Ensure your SKILL.md is complete

Make sure name, description, and any metadata.openclaw gating fields are set. Add a homepage URL if you have a project page.
2

Install the standalone ClawHub CLI and log in

npm i -g clawhub
clawhub login
3

Publish

clawhub skill publish ./path/to/hello-world
Add --version <version> or --owner <owner> to override the inferred version or publish under a specific owner. See ClawHub — Publishing and ClawHub CLI for the full flow, owner scoping, and other maintenance commands (clawhub sync, clawhub skill rename, …).

​
Best practices

  • Be concise — instruct the model on what to do, not how to be an AI.
  • Safety first — if your skill uses exec, ensure prompts do not allow arbitrary command injection from untrusted input.
  • Test locally — use openclaw agent --message "..." before sharing.
  • Use ClawHub — browse community skills at clawhub.ai before building from scratch.

Skills reference

Loading order, gating, allowlists, and SKILL.md format.

Skill Workshop

Proposal queue for agent-drafted skills.

Skills config

Full skills.* config schema.

ClawHub

Browse and publish skills on the public registry.

Building plugins

Plugins can ship skills alongside the tools they document.