Creating skills

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

Field	Description
name	Unique slug using lowercase letters, digits, and hyphens
description	One-line description shown to the agent and in discovery output

Optional frontmatter keys

Field	Default	Description
user-invocable	true	Expose the skill as a user slash command
disable-model-invocation	false	Keep 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-mode	raw	For 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" } }
---

Gating options

Key	Description
requires.bins	All binaries must exist on PATH
requires.anyBins	At least one binary must exist on PATH
requires.env	Each env var must exist in the process or config
requires.config	Each openclaw.json path must be truthy
os	Platform filter: ["darwin"], ["linux"], ["win32"]
always	Set true to skip all gates and always include the skill

Full reference: Skills — Gating.

Environment and API keys

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.

Related

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.