Creating Custom Skills for OpenClaw Agents

Skills determine when and how the agent applies tools. A skill is stored as a directory that holds a SKILL.md file, which combines YAML frontmatter with markdown instructions. OpenClaw pulls skills from multiple roots, applying a defined precedence order.

Create your first skill

Create the skill directory

Your workspace's skills/ folder is where skills reside:

mkdir -p ~/.openclaw/workspace/skills/hello-world

Subfolders can be used to organize skills, but the skill's name always comes from the SKILL.md frontmatter, never the directory path:

mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world

Write SKILL.md

Metadata lives in the frontmatter, while the body supplies the agent with 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

By default, OpenClaw monitors SKILL.md files beneath skill roots. If monitoring is off, or you're resuming an existing session, launch a fresh one so the agent sees the updated 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"

Alternatively, open a chat and ask the agent directly. Calling it explicitly by name is done with /skill hello-world.

SKILL.md reference

Required fields

Optional frontmatter keys

For gating-related fields (requires.bins, requires.env, etc.), consult Skills, Gating.

Using {baseDir}

Reference files within the skill directory without embedding absolute paths: the agent maps {baseDir} relative to the skill's own folder:

Run the helper script at `{baseDir}/scripts/run.sh`.

Adding conditional activation

Add gating so the skill loads only when its dependencies are present:

---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---

Gating options

Complete reference: Skills, Gating.

Environment and API keys

Connect an API key to a skill entry via openclaw.json:

{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}

That key gets injected into the host process for just that agent turn. It never reaches the sandbox; see sandboxed env vars.

Propose via Skill Workshop

When a skill has been written by an agent, or if you prefer a human check before it goes live, submit a Skill Workshop proposal rather than editing 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"

For proposals that come with supporting files, use --proposal-dir:

openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "A simple skill that prints a greeting." \
  --proposal-dir ./hello-world-proposal/

At the root of the directory, PROPOSAL.md must be present. Any supporting files belong under assets/, examples/, references/, scripts/, or templates/.

Once the review wraps up:

openclaw skills workshop inspect <proposal-id>
openclaw skills workshop evaluate <proposal-id>
openclaw skills workshop apply <proposal-id>

The complete proposal workflow is covered in Skill Workshop.

Publishing to ClawHub

Ensure your SKILL.md is complete

Confirm that name, description, and all metadata.openclaw gating fields are populated. If you maintain a project page, include a homepage URL.

Install the standalone ClawHub CLI and log in

npm i -g clawhub
clawhub login

Publish

clawhub skill publish ./path/to/hello-world

To override the version that gets inferred, or to publish under a specific owner, add --version <version> or --owner <owner>. The full workflow, including owner scoping and additional maintenance commands (clawhub sync, clawhub skill rename, ...), appears in ClawHub, Publishing and ClawHub CLI.

Best practices

Tip

• Keep it short, tell the model what to accomplish, not how to behave like an AI.
• Prioritize safety, when exec is part of your skill, make sure prompts block arbitrary command injection from untrusted input.
• Try it out, run openclaw agent --message "..." before you share.
• Check ClawHub, look through community skills at clawhub.ai before starting from nothing.

Related

• Skills reference, Covers loading order, gating, allowlists, and the SKILL.md format.

• Skill Workshop, The proposal queue for skills drafted by agents.

• Skills config, The complete skills.* config schema.

• ClawHub, Find and publish skills on the public registry.

• Building plugins, Plugins can bundle skills with the tools they document.