OpenClaw skills are reusable, packaged capabilities that extend your AI agent’s abilities. This guide will walk you through creating your first skill from scratch.

What Are OpenClaw Skills?

Skills in OpenClaw are self-contained modules that provide:

• Specialized Instructions – Step-by-step guidance for specific tasks
• Scripts & Tools – Executable code and utilities
• Documentation – Clear instructions for when and how to use the skill
• Reusability – Easy sharing and deployment across agents

Skill Structure

Every OpenClaw skill follows this structure:

my-skill/
├── SKILL.md           # Main skill instructions
├── scripts/           # Executable scripts
│   └── run.sh
├── examples/          # Usage examples
│   └── example.txt
└── README.md          # Documentation (optional)

Step 1: Create the Skill Directory

Skills are stored in the OpenClaw skills directory:

# Navigate to skills directory
cd ~/.openclaw/skills

# Create your skill folder
mkdir my-first-skill
cd my-first-skill

Step 2: Write the SKILL.md File

The SKILL.md file contains instructions for the AI agent. This is the core of your skill.

# My First Skill

## Purpose
This skill helps users greet people in multiple languages.

## When to Use
Use this skill when the user asks for greetings or translations.

## Instructions

1. Ask the user which language they want
2. Use the greeting lookup table below
3. Format the response nicely

## Greeting Table

| Language | Greeting |
|----------|----------|
| English  | Hello    |
| Spanish  | Hola     |
| French   | Bonjour  |
| German   | Guten Tag|
| Japanese | こんにちは |

## Example Usage

User: "How do I say hello in Spanish?"
Agent: "In Spanish, you say: **Hola**"

Step 3: Add Scripts (Optional)

If your skill needs to run code, add scripts:

mkdir scripts

Example script (scripts/translate.py):

#!/usr/bin/env python3
"""
Simple translation script for greetings
"""

greetings = {
    "english": "Hello",
    "spanish": "Hola",
    "french": "Bonjour",
    "german": "Guten Tag",
    "japanese": "こんにちは"
}

def get_greeting(language):
    lang = language.lower()
    return greetings.get(lang, "Unknown language")

if __name__ == "__main__":
    import sys
    if len(sys.argv) > 1:
        language = sys.argv[1]
        print(get_greeting(language))
    else:
        print("Usage: translate.py ")

Make it executable:

chmod +x scripts/translate.py

Step 4: Register the Skill

OpenClaw automatically discovers skills in the skills directory. To verify:

# Check skill status
openclaw skills list

# Should show your skill:
# my-first-skill - Available

Step 5: Test Your Skill

Chat with your agent and trigger the skill:

You: "How do I say hello in French?"

Agent reads SKILL.md → finds "French: Bonjour" → responds

Agent: "In French, you say: **Bonjour**"

Advanced: Using the Skill Creator Skill

OpenClaw includes a built-in skill for creating skills! Use it like this:

# Ask your agent:
"Create a new skill called 'weather-checker' that fetches weather data"

# The agent will:
# 1. Create the directory structure
# 2. Write SKILL.md with instructions
# 3. Add example scripts
# 4. Register the skill

Best Practices

1. Keep Skills Focused

Each skill should do one thing well:

• ✅ Good: “weather-forecast” skill
• ❌ Bad: “weather-and-stocks-and-news” skill

2. Write Clear Instructions

Your SKILL.md should be easy for the AI to follow:

## Instructions

1. Read the user's question
2. Extract the city name
3. Run `scripts/get-weather.sh CITY_NAME`
4. Format the output as a friendly message

3. Include Examples

Show the AI what good output looks like:

## Example

User: "What's the weather in Tokyo?"
Agent: "🌤️ Tokyo: 72°F, Partly Cloudy. High of 75°F today."

4. Handle Errors Gracefully

Include fallback instructions:

## Error Handling

If the script fails:
1. Tell the user the service is unavailable
2. Suggest trying again later
3. Do NOT show raw error messages

Skill Discovery

OpenClaw matches skills to user requests based on:

1. Skill name – e.g., “weather” matches “weather-forecast”
2. Description – Keywords in the SKILL.md
3. Context – What the user is asking about

Make your skill discoverable by using clear names and descriptions!

Sharing Your Skill

Once your skill works:

1. Test thoroughly – Try different phrasings and edge cases
2. Document well – Add a README.md with setup instructions
3. Share on ClawHub – Visit clawhub.com to publish

Example: Complete Weather Skill

Here’s a complete, production-ready skill:

SKILL.md

# Weather Forecast Skill

## Purpose
Get current weather and forecasts for any location.

## When to Use
- User asks about weather
- User asks about temperature
- User mentions forecast

## Dependencies
- curl (for API calls)
- jq (for JSON parsing)

## Setup
1. Get API key from wttr.in (no signup needed)
2. No configuration required - uses wttr.in

## Instructions

1. Extract location from user query
2. Run: `scripts/get-weather.sh "LOCATION"`
3. Parse the JSON response
4. Format as: "🌤️ [Location]: [Temp], [Condition]"

## Example

User: "What's the weather in Seattle?"
Agent: "🌤️ Seattle: 52°F, Light Rain. High of 58°F today."

scripts/get-weather.sh

#!/bin/bash
# Get weather for a location

LOCATION="$1"

if [ -z "$LOCATION" ]; then
    echo "Usage: get-weather.sh 'City Name'"
    exit 1
fi

# Fetch weather from wttr.in
curl -s "https://wttr.in/${LOCATION}?format=j1" | jq -r '
  "Temperature: \(.current_condition[0].temp_F)°F
  Condition: \(.current_condition[0].weatherDesc[0].value)
  High: \(.weather[0].maxtempF)°F
  Low: \(.weather[0].mintempF)°F"
'

Common Patterns

File Operations

## Instructions
1. Check if file exists: `test -f filename`
2. Read file: `cat filename`
3. Write file: `echo "content" > filename`

API Calls

## Instructions
1. Make API request: `curl -X POST https://api.example.com`
2. Parse JSON: `jq .field_name`
3. Handle errors: Check for empty response

User Input Validation

## Instructions
1. Check if required parameter provided
2. Validate format (email, URL, etc.)
3. Ask for clarification if needed

Troubleshooting

Skill Not Being Used

Problem: Agent doesn’t use your skill

Solutions:

• Check skill is listed: openclaw skills list
• Make the description more specific
• Use keywords the user might say

Scripts Not Running

Problem: Scripts fail to execute

Solutions:

• Verify permissions: chmod +x scripts/*.sh
• Check shebang line: #!/bin/bash
• Test script manually: ./scripts/test.sh

Paths Not Resolving

Problem: Files not found

Solutions:

• Use absolute paths in scripts
• Resolve paths relative to skill directory
• Check working directory: pwd

Next Steps

1. Explore existing skills – Check ~/.openclaw/skills/
2. Browse ClawHub – Find community skills at clawhub.com
3. Read the docs – Visit docs.openclaw.ai/skills
4. Join Discord – Get help at discord.com/invite/clawd

Resources

• Official Docs: docs.openclaw.ai
• GitHub: github.com/openclaw/openclaw
• Skill Hub: clawhub.com
• Community: discord.com/invite/clawd

Happy skill building! 🦞