Practical AI Guides

English

简体中文

English

简体中文

Appearance

Write Your Own Skill: SKILL.md and ClawHub Publishing ​

One-sentence goal: Complete your first hands-on OpenClaw skill development—write a hello-world skill from scratch, run through the full chain of "create directory → write SKILL.md → verify invocation", and figure out what to prepare before publishing to ClawHub.

Prerequisites ​

  • You have finished the previous lesson, "Getting Started with Skills: Installation, Usage, and Configuration", and can use existing skills.
  • OpenClaw is installed on your machine (Node 24.16.0+ or 26.1.0+), and the openclaw command is available.
  • A single terminal window is enough; no extra dependencies are needed.

Follow Along ​

Step 1: Create the Skill Directory ​

Skills live under the workspace's skills/ folder; one skill is one directory:

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

You can also nest subfolders for grouping (e.g., skills/personal/hello-world); the skill name is still determined by the frontmatter of SKILL.md, and invocation remains /hello-world.

Expected result: The skills/hello-world/ directory is created successfully; OpenClaw monitors the SKILL.md file under the skills root directory by default.

Step 2: Write SKILL.md ​

Create SKILL.md in the directory: write metadata in the frontmatter, and instructions for the agent in the body.

markdown
---
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!"
```

Three naming rules must be followed: name use only lowercase letters, digits, and hyphens; the directory name must match the frontmatter's name; description should be compressed to one line and no more than 160 characters—it is shown to the agent and also appears in slash command discovery.

Expected result: The file is saved as skills/hello-world/SKILL.md, and the frontmatter parses correctly.

Step 3: Verify Loading and Test ​

bash
openclaw skills list

If hello-world appears in the list, it is loaded. If you continued an old session or the watcher was turned off, refresh first:

bash
# 聊天里：归档当前会话，开新会话
/new
bash
# 或重启网关
openclaw gateway restart

Then test:

bash
openclaw agent --message "give me a greeting"

You can also simply state your need in the chat, or use /skill hello-world to explicitly invoke it by name.

Expected result: The agent executes the commands in the skill and replies with Hello from your custom skill!.

Verification ​

Check item by item:

  • openclaw skills list shows hello-world.
  • /skill hello-world produces output when explicitly invoked.
  • After modifying SKILL.md, /new or a new session after restarting the gateway can pick up the refreshed skill list.

If everything passes, your first skill is ready to use. A skill is essentially "a directory + SKILL.md"; once it passes testing, you can consider publishing it to ClawHub for others to install: install the standalone ClawHub CLI (npm i -g clawhub), log in with clawhub login, then publish with clawhub skill publish ~/.openclaw/workspace/skills/hello-world; for details such as registry review, refer to the official ClawHub documentation.

Common Pitfalls ​

  • Directory name and name mismatch: The skill name is determined by the frontmatter, and the directory name is just a container; but a mismatch can easily lead to wrong invocations, so keeping them aligned saves trouble.
  • description too long: Exceeding 160 characters slows down slash command discovery; compress it to one line.
  • Changes to SKILL.md not taking effect: Old sessions do not automatically refresh the skill list; try /new to start a new session or openclaw gateway restart first.

Next Lesson ​

Once you have your hand-written skill running, the next lesson, "Skill Workshop: Letting Claw Learn Skills on Its Own", has Claw draft, validate, and iterate skills for you—closing the loop of OpenClaw 2.0's "create-validate-install-invoke" chain.