How to Build Custom OpenClaw Skills (Step-by-Step)

What Are Skills and When to Build Them

Build a custom skill when:

• →You have a workflow you repeat more than 3–4 times
• →The task involves specific tools, APIs, or formats unique to your setup
• →You want the same capability available to both your main agent and sub-agents
• →You want a procedure that's consistently followed without variation

Skill Directory Structure

All custom skills live in ~/.openclaw/workspace/skills/. Each skill gets its own directory:

~/.openclaw/workspace/skills/
└── my-skill/
    ├── SKILL.md           # Required: instructions for the agent
    ├── references/        # Optional: docs, schemas, examples
    │   └── api-docs.md
    └── scripts/           # Optional: helper scripts
        ├── fetch-data.sh
        └── process.py

Writing the SKILL.md File

Every SKILL.md needs these sections:

# Skill Name

## Description
One paragraph describing what this skill does and WHEN to use it.
Use exact phrases users would say when asking for this.

## Prerequisites
- Required tools or CLI utilities
- Required environment variables or API keys

## Instructions

### Step 1: [First action]
[Detailed instructions for step 1]

### Step 2: [Second action]
[Detailed instructions for step 2]

## Output Format
Describe the expected output format.

## Error Handling
What to do when things go wrong.

Writing a Good Description

References and Scripts Directories

references/ — Supporting Docs

Use references/ for supporting documentation your agent might need to read during the task. Reference files are not loaded automatically — your SKILL.md should explicitly tell the agent to read them when needed:

## Instructions
Before starting, read references/api-docs.md for endpoint details.
The authentication flow is documented in references/auth.md.

scripts/ — Executable Helpers

Use scripts/ for executable helper scripts that your skill calls via the exec tool:

### Step 2: Fetch Data
Run the fetch script:
exec: bash scripts/fetch-data.sh --date today

Parse the JSON output and extract the "results" array.

Bash vs Python: When to Use Each

#!/usr/bin/env bash
set -e
cd "$PROJECT_DIR"
git pull origin main
npm run build && npm run deploy

#!/usr/bin/env python3
import sys, json, requests

data = json.load(sys.stdin)
results = [r for r in data if r['active']]
print(json.dumps(results))

Full Example: Stock Price Checker Skill

# Stock Price Checker

## Description
Fetch current stock prices, percentage changes, and basic metrics
for any US-listed stock ticker. Use when asked about stock prices,
market data, portfolio values, or ticker lookups.

## Prerequisites
- ALPHA_VANTAGE_API_KEY environment variable set
- Python 3.8+ installed
- requests library: pip install requests

## Instructions

### Step 1: Identify Tickers
Extract all stock ticker symbols from the user's request.
Normalize to uppercase (e.g., "apple" → "AAPL").

### Step 2: Fetch Data
For each ticker, run:
exec: python3 scripts/fetch-stock.py --ticker {TICKER}

### Step 3: Format Output
Present results as a clean table:
| Ticker | Price | Change | Change % | Volume |

## Error Handling
If a ticker is not found: note it as "not found" and continue.
If API rate limit hit: wait 15 seconds and retry once.

## Output Format
Markdown table with all requested tickers.
Include timestamp of data fetch.

Using the skill-creator Skill

OpenClaw ships with a skill-creator skill that helps you build other skills. Just describe what you want:

"Create a skill for posting to my Ghost blog.
It should: authenticate with Ghost Admin API,
create draft posts, publish posts, and update existing ones.
The API key is stored in ~/.openclaw/.env as GHOST_ADMIN_KEY."

The agent will create the full skill directory, SKILL.md, and any required scripts.

Testing Your Skill

1. 1

   Describe a simple use case

   Ask your agent to use the skill with a basic request. Watch if it correctly identifies and loads your skill.

2. 2

   Check the skill is being loaded

   If the agent isn't using your skill, check the description section — it needs to match the phrases you're using.

3. 3

   Test edge cases

   Try requests that should trigger error handling. Make sure the agent follows your error instructions, not generic behavior.

4. 4

   Iterate and refine

   Skills improve with use. After each session where the skill ran, review what went well and what was ambiguous. Update SKILL.md accordingly.