OpenClaw Skill Manifest Reference: Format, Schema & Examples

Every OpenClaw Skill starts with a manifest file—skill.yaml—that tells OpenClaw what the Skill does, what permissions it needs, and how to run it. This reference covers every field in the manifest format, with examples you can copy and adapt for your own Skills.

What Is a Skill Manifest?

A Skill manifest (skill.yaml) is the configuration file at the root of every OpenClaw Skill. It defines the Skill's identity (name, version, author), its capabilities (what it can do), its requirements (permissions, configuration), and its entry point (how to run it). When you install a Skill from ClawHub, OpenClaw reads this manifest to understand what the Skill needs and how to integrate it safely.

Manifest Schema Overview

Here is the complete schema for a skill.yaml file. Required fields are marked. All other fields are optional but recommended for published Skills.

# skill.yaml - Complete Schema
name: string          # Required. Unique skill identifier
version: string       # Required. Semver format (1.0.0)
author: string        # Required. Your username or org
description: string   # Required. What the skill does
license: string       # Optional. Default: MIT

permissions:          # Required. List of needed permissions
  - network           # HTTP/HTTPS access
  - filesystem        # Read/write files
  - browser           # Browser automation
  - shell             # Execute shell commands
  - notifications     # Send user notifications

config:               # Optional. User-configurable options
  api_key:
    type: string
    required: true
    description: "API key for the service"
    secret: true      # Stored in vault, not plaintext
  refresh_interval:
    type: number
    required: false
    default: 300
    description: "Check interval in seconds"

entryPoint:           # Required. How to run the skill
  type: string        # natural | typescript | shell
  path: string        # File path (for ts/shell)
  prompt: string      # Natural language (for natural type)

triggers:             # Optional. Auto-activation rules
  keywords: []        # Trigger on these words
  schedule: string    # Cron expression
  webhook: string     # Webhook endpoint path

Field-by-Field Reference

Name: A unique identifier using lowercase letters, numbers, and hyphens. Must be unique on ClawHub. Example: weather-reporter. Version: Semantic versioning (major.minor.patch). Increment major for breaking changes, minor for new features, patch for fixes. Author: Your ClawHub username or organization name. This is verified when publishing. Description: A clear, concise explanation of what the Skill does. This appears in search results on ClawHub, so make it descriptive. License: The open-source license for your Skill. Defaults to MIT if not specified. Common choices: MIT, Apache-2.0, GPL-3.0.

Permissions Reference

Permissions control what a Skill can access on the user's system. Users see the requested permissions before installing a Skill, similar to mobile app permissions. Request only what you need—Skills with fewer permissions get more installs.

# Available permissions:
permissions:
  - network        # Make HTTP/HTTPS requests
  - filesystem     # Read and write local files
  - browser        # Control Chrome/Chromium browser
  - shell          # Execute shell commands
  - notifications  # Send notifications to user
  - calendar       # Access calendar data
  - email          # Access email (read/send)
  - vault          # Access encrypted vault secrets
  - trading        # Access trading module
  - voice          # Use voice/TTS capabilities

# Example: A weather skill only needs network
permissions:
  - network
  - notifications

Configuration Options

The config section defines user-configurable options for your Skill. Each option has a type, description, and optional default value. Options marked as secret are stored in the encrypted vault instead of plaintext config files. Supported types are: string, number, boolean, and array.

# Config field types and options
config:
  api_key:
    type: string
    required: true
    description: "Your API key"
    secret: true           # Stored encrypted in vault
  
  check_interval:
    type: number
    required: false
    default: 300
    description: "Check interval in seconds"
    min: 60                # Minimum value
    max: 86400             # Maximum value
  
  enabled_features:
    type: array
    required: false
    default: ["alerts", "reports"]
    description: "Which features to enable"
  
  verbose_logging:
    type: boolean
    required: false
    default: false
    description: "Enable detailed logging"

Entry Point Types

Skills can be implemented in three ways. Natural language is the simplest—you describe what the Skill should do, and OpenClaw generates the logic at runtime. TypeScript gives you full programmatic control with access to the OpenClaw SDK. Shell scripts are useful for wrapping existing CLI tools. For most use cases, start with natural language and upgrade to TypeScript only if you need complex logic or external npm packages.

Complete Working Example

Here is a fully working Skill manifest for a stock price checker that monitors prices and sends alerts when they cross a threshold.

# skill.yaml - Stock Price Alert Skill
name: stock-price-alert
version: 1.2.0
author: openclaw-community
description: Monitor stock prices and get alerts when
  they cross your target price. Supports all major
  exchanges via Alpha Vantage API.
license: MIT

permissions:
  - network
  - notifications

config:
  alpha_vantage_key:
    type: string
    required: true
    description: "Alpha Vantage API key (free tier works)"
    secret: true
  default_exchange:
    type: string
    required: false
    default: "NYSE"
    description: "Default stock exchange"

entryPoint:
  type: natural
  prompt: |
    You are a stock price monitoring skill.
    When asked to watch a stock, use the Alpha Vantage
    API to check its current price.
    Compare against the user's target price.
    Send a notification if the target is reached.
    Include current price, change %, and volume.

triggers:
  keywords: ["stock price", "watch stock", "price alert"]
  schedule: "*/15 * * * *"  # Check every 15 minutes

Validating Your Manifest

Before publishing, always validate your manifest to catch errors early. OpenClaw provides a built-in validation command that checks for missing required fields, invalid types, permission conflicts, and schema compliance.

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

# Expected output for a valid manifest:
# ✓ name: valid
# ✓ version: valid semver
# ✓ author: valid
# ✓ description: present
# ✓ permissions: valid
# ✓ config: schema valid
# ✓ entryPoint: valid
# All checks passed!

# Common validation errors:
# ✗ name contains uppercase letters
# ✗ version is not valid semver
# ✗ required config field missing type
# ✗ unknown permission: database

Common Errors & Fixes

Here are the most frequent issues developers encounter when creating Skill manifests, along with their solutions. "Unknown permission" means you used a permission name that does not exist—check the permissions reference above. "Invalid entry point type" means the type must be natural, typescript, or shell. "Config field missing type" means every config option needs an explicit type declaration. "Name already taken" on ClawHub means another Skill has that name—choose a more specific name for yours.

Frequently Asked Questions

Should I use natural language or TypeScript for my Skill?

Start with natural language—it is faster to develop and works well for 80% of use cases. Switch to TypeScript if you need external npm packages, complex data processing, or precise control over execution flow.

How do I update a published Skill?

Increment the version number in skill.yaml and run openclaw skills publish again. Users with auto-update enabled will get the new version automatically. For breaking changes, increment the major version.

Can I charge for my Skill?

ClawHub currently supports free Skills only. Paid Skills and sponsorship models are on the roadmap. For now, consider accepting donations via GitHub Sponsors or similar platforms.

Start Building

Now that you understand the manifest format, create your first Skill and publish it to ClawHub.