How to Create Custom Skills in OpenClaw: Step-by-Step Guide

The fastest way to extend OpenClaw is to build a skill. Skills are modular, shareable packages that teach your agent how to do something new. A well-written skill turns a vague instruction into a reliable sequence of tool calls. This guide walks through creating a custom skill from scratch, testing it locally, and publishing it to ClawHub.

What is an OpenClaw skill?

An OpenClaw skill is a directory containing a SKILL.md file and optional helper scripts. The SKILL.md file has two sections: YAML frontmatter that tells OpenClaw how to load the skill, and a Markdown body that instructs the agent on what to do when the skill is invoked.

Skills live in one of three locations:

• Managed skills — ~/.openclaw/skills/ (available to all sessions and agents)
• Project skills — ./skills/ inside a repo (scoped to that project)
• Installed skills — downloaded from ClawHub into the managed directory

OpenClaw auto-discovers skills via a file watcher. You do not need to restart anything — new SKILL.md files are detected within 250ms.

Anatomy of a SKILL.md

Every skill needs a SKILL.md file. Here is the minimal template:

---
name: my-first-skill
description: A brief one-line description of what this skill does.
user-invocable: true
requires:
  bins:
    - curl
    - jq
---

# My First Skill

When the user asks to do [specific thing], use the exec tool to run:

curl -s https://api.example.com/endpoint | jq '.results'

Format the output as a Markdown table and present the results.

The key frontmatter fields:

• name — identifier in hyphen-case. Doubles as the slash command when user-invocable is true.
• description — one-line summary the agent uses to decide relevance. Keep it specific.
• user-invocable — set to true to make it a slash command (e.g., /my-first-skill).
• requires.bins — binary dependencies. OpenClaw checks for these before running the skill and skips it if they are missing, preventing runtime failures.

Step 1: Plan your skill

Before you write anything, decide what your skill will do. The best skills are narrow and deterministic. If a human can describe the task in a single sentence, a skill can probably handle it.

Examples of good skill boundaries:

• Convert a Markdown file to DOCX
• Fetch weather data for a location
• Scaffold a new React component with tests
• Search your company wiki by keyword
• Generate an OpenGraph image from a template

If your skill needs to make API calls, those should be clearly documented. If it needs credentials, reference environment variables rather than embedding secrets in the skill file.

Step 2: Create the skill directory

Create a new directory inside your managed or project skills folder:

mkdir -p ~/.openclaw/skills/my-first-skill
cd ~/.openclaw/skills/my-first-skill

The directory name should be descriptive and use hyphen-case. OpenClaw uses the directory name as the skill slug, which matters for ClawHub publishing.

Step 3: Write the SKILL.md

Create SKILL.md in your skill directory. Start with the frontmatter block, then write the Markdown body.

Frontmatter example:

---
name: weather-forecast
description: Get a 3-day weather forecast for any US city.
user-invocable: true
requires:
  bins:
    - curl
---

Body instructions:

Write the body as instructions to the agent. Be concise. Tell the agent what to do, not how to be an AI. A good body follows this structure:

1. Context — when should this skill be invoked?
2. Parameters — what does the skill need from the user?
3. Steps — the exact tool calls to make, in order.
4. Output — how to present results to the user.
5. Errors — what to do if something goes wrong.

Example body for a weather skill:

# Weather Forecast Skill

Invoke this skill when the user asks about weather for a specific city.

## Parameters

Ask the user for the city name if they have not provided one. Accept "city, state" or just "city" for well-known locations.

## Steps

1. Use `exec` to run: `curl -s "wttr.in/{city}?format=3"`
2. Parse the temperature and condition from the output.
3. Display the result in a clear format.

## Output Format

Present: "Current weather in [City]: [temperature], [condition]."

## Error Handling

If curl fails, ask the user if the city name is correct and try again.

Step 4: Add helper scripts (optional)

For complex logic that is impractical to express in Markdown, add helper scripts. These can be Python, Bash, Node.js, or TypeScript. Place them in the skill directory or a scripts/ subfolder.

Your SKILL.md body then references the script path. For example, a skill that generates OpenGraph images might have:

scripts/
  generate-og-image.py
  templates/
    default-template.svg
SKILL.md

And the SKILL.md body would tell the agent to run:

python3 scripts/generate-og-image.py \
  --title "$TITLE" \
  --output "$OUTPUT_PATH" \
  --template scripts/templates/default-template.svg

Helper scripts must be self-contained. If they import external libraries, document that in the requires section or as a comment in the file. Prefer uv for managing Python dependencies to keep things portable.

Step 5: Test your skill

OpenClaw detects new skills automatically via its file watcher. To test, open a session and either:

• Type the slash command (e.g., /weather-forecast Portland) if the skill is user-invocable, or
• Ask your agent to perform the task and see if it picks up the skill

To test from the CLI:

openclaw agent --message "What is the weather in Portland?"

Check the agent logs to confirm the skill was invoked. If it does not appear, check that:

• The SKILL.md file is valid YAML and Markdown
• The description is accurate enough for the agent to match
• Required binaries are installed and on $PATH
• The skill is in the correct directory (~/.openclaw/skills/ or project ./skills/)

Step 6: Publish to ClawHub

Once your skill is working locally, share it with the community by publishing to ClawHub. ClawHub is the official skill registry for OpenClaw, and it uses npm for distribution.

To publish:

# Install the ClawHub CLI if you have not already
npm install -g clawhub

# Publish from your skill directory
cd ~/.openclaw/skills/weather-forecast
clawhub publish

Before publishing, ensure your skill has:

• A clear, unique name
• A description that helps the agent (and humans) understand its purpose
• Complete instructions for every step
• Error handling documented in the body
• No embedded secrets or hardcoded paths specific to your machine

After publishing, anyone can install your skill with: clawhub install weather-forecast.

Real example: A skill that fetches booth data

Here is a real-world skill that demonstrates the pattern. This skill queries the Booth Beacon API for photo booth locations in a city:

---
name: booth-beacon-search
description: Search Booth Beacon for analog photo booth locations in any city.
user-invocable: true
requires:
  bins:
    - curl
---

# Booth Beacon Search

When the user wants to find photo booths in a city, use the Booth Beacon API.

## Steps

1. Ask the user for the city name if not provided.
2. Run: `curl -s "https://boothbeacon.org/api/v1/cities?q=SLUG"`
3. Parse the JSON response.
4. List each booth with its name, address, and machine type.
5. If the API returns no results, suggest checking the spelling or trying a nearby city.

## Output Format

"Found [N] photo booths in [City]:
- [Booth Name] — [Address] ([Machine Type])"

This skill is narrow (one API, one purpose), deterministic (same input produces same output structure), and self-documenting (the body explains exactly when and how to use it).

Best practices

Common mistakes

• Vague descriptions — "Helps with various tasks" tells the agent nothing. Be specific.
• Missing error handling — When an API returns a 500, the agent should know what to do next, not retry blindly.
• Over-engineering — Start with a Markdown-only skill. Add scripts only when the logic genuinely cannot be expressed in tool calls.
• Environment-specific paths — Do not hardcode /Users/yourname/.... Use relative paths from the skill directory or environment variables.
• Skipping the pre-push hook — When your skill is in a repo, run the project's pre-push hook before committing. A broken build breaks the deploy.

Troubleshooting

My skill is not showing up. Check that the file is named SKILL.md (case-sensitive). Verify YAML syntax with yamlint or paste it into a YAML validator. Confirm the skill is in one of the three recognized locations.

The agent is not invoking my skill. The description may be too vague or too specific. Rewrite it to match the language a user would naturally use when asking for this capability.

My helper script fails. Check that required binaries are installed. Use which script to verify paths. Test the script independently before marking the skill as complete.

Publishing to ClawHub fails. Ensure the skill directory has a unique name. Check that you are logged into npm. Verify that the name in frontmatter matches the directory name.

Next steps

Now that you have built your first skill, here are places to go deeper:

• Complete guide to using OpenClaw skills — covers installing skills from ClawHub and managing your skill directory
• OpenClaw routing rules — decide when a skill, a loop, or an agent delegation is the right tool
• Parallel task execution with OpenClaw loops — skill composition patterns for batch processing
• Scheduling AI agent tasks with cron — run your skill on a timer
• The real cost of running an AI agent — why modular skills reduce operational overhead

Summary

Creating a custom OpenClaw skill is the fastest way to package capability your agent can reuse. The recipe is simple: plan a narrow scope, write a SKILL.md with frontmatter and body, add helper scripts only when needed, test locally, and publish to ClawHub for others to use. A small library of well-written skills compounds over time — each one reduces the friction of repeating the same task manually.

The skill ecosystem is still young. Every skill you publish raises the floor for what the community can build together. Start with something small. The file watcher will pick it up in 250ms.