Skill Development Guide

Build Your Own Skills

Skills (plugins) extend what your OpenClaw agent can do. This guide covers creating, testing, and publishing custom skills — from file structure to the "Being scanned" state.

Whether you're building a simple API wrapper or a complex browser automation skill, this guide walks you through the complete development lifecycle.

Jump to Section

File Structure Manifest Format Local Testing Publishing "Being Scanned" State Sandbox Env Variables

Skill File Structure

Every skill follows this directory structure:

my-skill/

manifest.json # Required: skill metadata and tool definitions

index.js # Required: entry point

package.json # Optional: npm dependencies

README.md # Optional: documentation

.env.example # Optional: required env vars template

Manifest Format

The manifest.json defines your skill's metadata, tools, and requirements:

Example manifest.json

{
  "name": "my-custom-skill",
  "version": "1.0.0",
  "description": "A custom skill that does X",
  "author": "your-name",
  "tools": [
    {
      "name": "my_tool",
      "description": "Does something useful",
      "parameters": {
        "type": "object",
        "properties": {
          "input": {
            "type": "string",
            "description": "The input to process"
          }
        },
        "required": ["input"]
      }
    }
  ],
  "env": ["MY_API_KEY"],
  "sandbox": true
}

name

Unique identifier. Use lowercase with hyphens.

tools

Array of tool definitions with JSON Schema parameters. Each tool becomes available to the agent.

env

Environment variables your skill needs. These must be passed to the sandbox explicitly.

sandbox

Set to true if the skill should run in Docker isolation (recommended for skills that execute code).

Local Testing

Test your skill locally before publishing:

Install skill locally

# From your skill directory:
openclaw skills install ./my-skill

# Restart to load the new skill
openclaw gateway restart

# Test it in chat:
openclaw run "Use my_tool with input 'test'"

Check skill is loaded

# List installed skills
openclaw skills list

# Check skill logs
openclaw logs --follow | grep -i "my-skill"

Testing Tips

Test with sandbox off first to simplify debugging
Check gateway logs for any initialization errors
Verify tool parameters match your manifest schema
Test edge cases (empty input, large input, special characters)

Publishing Workflow

Publish your skill

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

# Publish to the skill registry
openclaw skills publish ./my-skill

Validate

openclaw skills validate checks manifest format, tool schemas, and file structure.

Publish

openclaw skills publish uploads your skill to the registry and triggers a security scan.

Scanning

The skill enters "Being scanned" state while automated security checks run (1-5 minutes).

Available

Once scanning passes, the skill appears in the registry and can be installed by others.

"Being Scanned" State Troubleshooting

After publishing, your skill enters a "Being scanned" state. If it stays in this state for more than 10 minutes, something went wrong.

Check skill status

Run openclaw skills list --mine to see current scanning status.

Re-publish if stuck

If scanning takes too long, try openclaw skills publish again. This triggers a new scan.

Check for disallowed patterns

The scanner rejects skills that shell out to curl/wget, read /etc/passwd, or attempt network access beyond declared endpoints.

Check and re-publish

# Check current status
openclaw skills list --mine

# Re-publish to trigger new scan
openclaw skills publish ./my-skill

# Check logs for scan errors
openclaw logs --follow | grep -i "skill\|scan"

Sandbox Environment Variables

Skills running in sandbox mode (Docker) do not inherit the host's environment variables. If your skill needs API keys or configuration via env vars, you must pass them explicitly.

Pass env vars to sandboxed skills

# Method 1: Set via config (persistent)
openclaw config set agents.defaults.sandbox.env '{"MY_API_KEY": "value", "ANOTHER_VAR": "value2"}' --json
openclaw gateway restart

# Method 2: Disable sandbox (development only)
openclaw config set agents.defaults.sandbox.mode off
openclaw gateway restart

Security Note

Be careful which env vars you expose to sandboxed skills. Only pass variables that the skill explicitly needs (declared in the env field of manifest.json). Never expose your main API keys to untrusted third-party skills.

Related Resources

Skill ecosystem and tools: