How to Create Custom Skills for OpenClaw

What Are OpenClaw Skills?

Skills are the building blocks that give OpenClaw agents their capabilities. A skill is essentially a tool or function that an agent can invoke — like searching the web, writing a file, calling an API, or processing data.

The Skill Store comes with hundreds of pre-built skills, but sometimes you need something custom. Maybe you need to integrate with a proprietary API, implement a domain-specific algorithm, or create a workflow that doesn't exist yet.

Skill Architecture

Every OpenClaw skill has three parts:

• Definition: What the skill does, its parameters, and return types
• Implementation: The actual code that executes when the skill is invoked
• Metadata: Description, documentation, and configuration for the Skill Store

Creating Your First Skill

Step 1: Scaffold the Skill

openclaw skill create my-custom-skill

This generates a skill template with the proper structure:

my-custom-skill/
├── src/
│   ├── index.ts        // Main skill implementation
│   └── types.ts        // Type definitions
├── tests/
│   └── skill.test.ts   // Test suite
├── skill.config.ts        // Skill metadata
└── README.md

Step 2: Define the Skill Interface

In src/types.ts, define what your skill accepts and returns:

export interface SkillInput {
  query: string;
  maxResults?: number;
}

export interface SkillOutput {
  results: Array<{ title: string; summary: string }>;
  totalFound: number;
}

Step 3: Implement the Skill

In src/index.ts, write the implementation:

import { defineSkill } from '@openclaw/sdk';
import type { SkillInput, SkillOutput } from './types';

export default defineSkill<SkillInput, SkillOutput>({
  name: 'my-custom-skill',
  description: 'Searches a custom database and returns results',
  execute: async (input) => {
    const response = await fetch("https://api.example.com/search?q=" + input.query);
    const data = await response.json();
    return {
      results: data.items.slice(0, input.maxResults || 10),
      totalFound: data.total,
    };
  },
});

Step 4: Test Your Skill

openclaw skill test --local

The test harness lets you run your skill with sample inputs and verify the outputs match expectations.

Step 5: Install and Use

Install the skill into your agent:

openclaw skill install ./my-custom-skill

Your agent can now use the skill in its task execution.

Advanced Skill Patterns

Multi-Step Skills

Some skills need to perform multiple operations. Use the step system:

export default defineSkill({
  name: 'research-and-summarize',
  steps: [
    { name: 'search', execute: searchFn },
    { name: 'filter', execute: filterFn },
    { name: 'summarize', execute: summarizeFn },
  ],
});

Skills with Authentication

For skills that need API keys or credentials, use the secure config system:

export default defineSkill({
  name: 'github-integration',
  config: {
    apiKey: { type: 'secret', required: true, description: 'GitHub API token' },
  },
  execute: async (input, { config }) => {
    // config.apiKey is securely injected at runtime
  },
});

Skills with State

Need to maintain state between invocations? Use the skill state API:

execute: async (input, { state }) => {
  const previousResults = await state.get('lastSearch');
  // ... do work ...
  await state.set('lastSearch', newResults);
}

Publishing to the Skill Store

Ready to share your skill with the world? The Skill Store makes it easy:

• Prepare: Write clear documentation, include examples, and ensure tests pass
• Publish: openclaw skill publish
• Price: Set your pricing model (free, paid, or subscription)
• Maintain: Respond to issues, update regularly, and watch usage metrics in your ClawHQ dashboard

Skill Development Best Practices

• Single responsibility: Each skill should do one thing well
• Clear descriptions: Agents use your description to decide when to use the skill — make it precise
• Error handling: Return meaningful errors that help the agent (and you) understand what went wrong
• Idempotency: When possible, make skills safe to retry
• Rate limiting: If your skill calls external APIs, implement rate limiting to avoid hitting quotas

Ready to manage your agent fleet? Start managing your fleet for free→