Building Custom Skills for OpenClaw - Developer Guide

Skills are the building blocks that extend OpenClaw's capabilities. Whether you want to integrate a niche API, automate a specific workflow, or build something entirely new, this guide walks you through the complete lifecycle of creating and publishing an OpenClaw Skill.

What Are Skills?

Skills are modular packages that add new capabilities to OpenClaw. They can range from simple single-purpose tools (checking stock prices, fetching weather) to complex multi-step workflows (managing a full deployment pipeline). Skills are installed via ClawHub and become available as tools that OpenClaw can invoke during conversations.

Examples of popular community Skills: weather-reporter, flight-tracker, github-manager, smart-home-controller, news-digest, price-alert, appointment-booker, recipe-finder

Anatomy of a Skill

Every OpenClaw Skill follows a standard structure. At minimum, a Skill needs a manifest file (skill.yaml) and an entry point. The manifest defines metadata, required permissions, and configuration options.

# skill.yaml
name: my-weather-skill
version: 1.0.0
author: your-username
description: Get weather forecasts for any location
permissions:
  - network    # Needs HTTP access
config:
  api_key:
    type: string
    required: true
    description: OpenWeather API key

# Entry point options:
# 1. Natural language (simplest)
# 2. JavaScript/TypeScript module
# 3. Shell script

Natural Language Skills (The Easy Way)

The simplest way to create a Skill is with natural language. You describe what the Skill should do, and OpenClaw generates the implementation. This is perfect for simple automations and API integrations.

# Create a skill with natural language
openclaw skills create weather-reporter \
  --description "Check weather for a given city using wttr.in. \
  Return temperature, conditions, and 3-day forecast. \
  Format output as a clean summary."

# Test it immediately
openclaw skills test weather-reporter --input "Weather in San Francisco"

# Install locally
openclaw skills install ./weather-reporter

TypeScript Skills (Full Control)

For more complex Skills, write a TypeScript module. This gives you full control over the implementation, access to npm packages, and type safety.

// skills/price-tracker/index.ts
import { Skill, SkillContext, SkillResult } from '@openclaw/sdk';

export default class PriceTracker implements Skill {
  name = 'price-tracker';
  description = 'Track product prices and alert on drops';

  async execute(ctx: SkillContext): Promise<SkillResult> {
    const { url, targetPrice } = ctx.params;

    // Use OpenClaw's built-in browser to scrape the price
    const page = await ctx.browser.newPage();
    await page.goto(url);
    const price = await page.evaluate(() => {
      // Extract price from the page
      return document.querySelector('.price')?.textContent;
    });
    await page.close();

    const currentPrice = parseFloat(price || '0');

    if (currentPrice <= targetPrice) {
      await ctx.notify(
        `Price drop alert! ${url} is now $${currentPrice} ` +
        `(target: $${targetPrice})`
      );
    }

    return {
      price: currentPrice,
      belowTarget: currentPrice <= targetPrice
    };
  }
}

Testing Your Skill

OpenClaw provides built-in testing tools. Test locally before publishing to ensure your Skill works correctly in various scenarios.

# Run the Skill with test input
openclaw skills test my-skill --input "test query"

# Run with specific config
openclaw skills test my-skill \
  --input "Weather in Tokyo" \
  --config '{"api_key": "test-key"}'

# Run in sandbox mode (recommended for untrusted code)
openclaw skills test my-skill --sandbox

# Verbose output for debugging
openclaw skills test my-skill --input "test" --verbose

Publishing to ClawHub

Once your Skill is tested and ready, publish it to ClawHub so the community can discover and install it. You'll need a GitHub account for verification.

# Validate your skill manifest
openclaw skills validate ./my-skill

# Publish to ClawHub
openclaw skills publish ./my-skill

# After publishing, anyone can install it:
# openclaw skills install my-skill

Best Practices

Request Minimal Permissions

Only request the permissions your Skill actually needs. Users are more likely to install Skills with narrow permission scopes.

Handle Errors Gracefully

Always handle network failures, API rate limits, and invalid inputs. Return clear error messages that help the user understand what went wrong.

Make Configuration Easy

Provide sensible defaults and clear descriptions for all config options. Use the config schema to validate user input.

Design for Idempotency

Skills may be retried on failure. Ensure running a Skill twice with the same input doesn't cause unintended side effects.

Write Clear Documentation

Include a README with examples, expected inputs/outputs, and configuration instructions. Good docs significantly increase adoption.

What's Next?

Now that you know how to build Skills, explore existing Skills for inspiration and check out the advanced subagent orchestration patterns.