Creating Custom Skills for OpenClaw Agents

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

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

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

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

Optional frontmatter keys

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

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

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.

Install the standalone ClawHub CLI and log in

npm i -g clawhub
clawhub login

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

Tip

• 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.