How to Publish an OpenClaw Skill to ClawHub
You have built an OpenClaw skill that automates a useful workflow. It scrapes data, sends alerts, or orchestrates a multi-step process that saves hours of manual work. Now comes the next question: how do other people find and use it? The answer is ClawHub, the registry where OpenClaw skills are published, discovered, and versioned.
This guide walks through every step of publishing a skill to ClawHub — from structuring your skill directory and writing clear documentation to using the clawhub CLI for publishing and managing updates. If you have not written a skill yet, start with the OpenClaw skill building guide. If you want the broader picture of how skills work inside OpenClaw, read the skills usage guide first.
What ClawHub Is and Why It Matters
ClawHub is the skill registry for OpenClaw's ecosystem. Like npm for Node.js or the VS Code marketplace, ClawHub is where skill authors publish their work and where users search, install, and update skills. The registry stores skill metadata, handles versioning, and provides the API that the clawhub CLI uses to search and install skills.
Publishing a skill on ClawHub accomplishes three things. First, it makes your skill discoverable through the clawhub search command, so other OpenClaw users can find it without knowing where to look. Second, it gives your skill a versioned release history: users can install a specific version, update to the latest, or pin to a trusted release. Third, it provides automated distribution — when a user runs clawhub install <skill-name>, the CLI downloads the latest published version and places it in the correct skills directory.
If you are already familiar with OpenClaw's cron scheduling and how skills integrate with timed execution, publishing is the logical next step: it takes a skill from a local tool to a shared resource.
Prerequisites
Before publishing, make sure you have the following:
- OpenClaw installed and running on your machine
- The
clawhubCLI installed (npm install -g clawhub) - A ClawHub account with a registered publisher profile
- A completed skill directory that follows the AgentSkills specification
- Your skill folder placed in your OpenClaw skills directory (typically
~/.openclaw/skills/)
The ClawHub CLI handles authentication through an API token. If you have not logged in yet, run clawhub login and follow the prompts. This stores your token locally so you do not need to authenticate with every publish.
Step 1: Structure Your Skill Directory
ClawHub expects skills to follow a specific directory layout. The root of your skill folder must contain a SKILL.md file. Everything else is optional but recommended:
my-awesome-skill/
├── SKILL.md # Required: the skill definition
├── scripts/ # Optional: helper scripts
│ └── run.sh
├── references/ # Optional: supporting docs
│ └── api-spec.md
├── templates/ # Optional: output templates
│ └── report.md
└── examples/ # Optional: usage examples
└── example-output.jsonThe SKILL.md file is the heart of your skill. OpenClaw reads this file to understand what the skill does, when it should be triggered, and how the agent should use it. The file follows a five-section pattern:
- Description: A one-to-two sentence summary of what the skill does
- Triggers: Keywords or patterns that should activate this skill
- Usage: Instructions for how the agent should use the skill's tools and scripts
- Configuration: Any setup steps, environment variables, or dependencies
- Common Tasks: Typical operations the skill handles, mapped to specific workflows
Step 2: Write a Searchable SKILL.md
The SKILL.md file's description section is what appears in ClawHub search results. Write a description that makes the skill's purpose immediately clear. Avoid generic phrases like "a useful skill" — instead, be specific: "Scrapes photo booth availability data from Yelp and normalizes it into a Supabase database."
The triggers section determines when OpenClaw automatically loads your skill. List natural language phrases that users might say. If your skill handles photo booth data, include triggers like "photo booth locations," "booth near me," and "find a photo booth." The more triggers you include, the more likely your skill will be activated when relevant.
A well-written SKILL.md includes a reference to the SKILL.md path at the top so OpenClaw can find it. Here is a minimal valid example:
# My Awesome Skill Scrapes photo booth data from public APIs and syncs it to a database. ## Triggers - photo booth - find a booth - sync booth data ## Usage Run `scripts/run.sh` to trigger a sync. The script expects a JSON config at `config.json` in the skill root. ## Configuration No external dependencies. Requires curl and jq. ## Common Tasks - Sync all booths: `scripts/run.sh --full` - Check last sync: `cat last_sync.txt`
Step 3: Install and Authenticate the clawhub CLI
With your skill directory ready, install the ClawHub CLI. It is distributed through npm for easy cross-platform installation:
npm install -g clawhub # Verify the installation clawhub --version # Log in to your ClawHub account clawhub login
The login command will prompt you for your API token, which you can generate from your ClawHub profile settings page. The token is stored in ~/.config/clawhub/config.json and reused for subsequent commands.
Step 4: Publish Your Skill
Publishing is a single command. Navigate to the directory containing your skill folder and run:
# Navigate to your skills directory cd ~/.openclaw/skills # Publish the skill clawhub publish my-awesome-skill # Or publish from a specific path clawhub publish /path/to/my-awesome-skill
The CLI will validate your skill structure, check that SKILL.md exists and follows the expected format, and then upload it to ClawHub. If validation fails, the CLI reports the specific issue — missing sections in SKILL.md, unsupported file types, or oversized directories.
On successful publish, the CLI returns the skill's name and version number. By default, the first publish creates version 1.0.0.
Step 5: Version Your Skill
As you update your skill, use semantic versioning to communicate the scope of changes. The clawhub CLI makes version management straightforward:
# Publish a patch (bug fixes, documentation changes) clawhub publish my-awesome-skill --patch # Publish a minor update (new features, backward compatible) clawhub publish my-awesome-skill --minor # Publish a major update (breaking changes) clawhub publish my-awesome-skill --major # Publish a specific version clawhub publish my-awesome-skill --version 2.0.0
Users install skills with version constraints. If you publish a breaking change as a major version bump, users pinned to the previous major version are not affected. This is especially important for skills that other people depend on in automated workflows. For more on setting up automated workflows, see the cron job automation guide.
Step 6: Verify Your Published Skill
After publishing, verify that everything works correctly:
# Search for your skill clawhub search my-awesome-skill # View your skill's details clawhub info my-awesome-skill # In a test environment, install the published version clawhub install my-awesome-skill # Check installed skills clawhub list --installed
Running clawhub install my-awesome-skill from a clean environment tests the full flow — search, download, and placement. This is the best way to confirm that your skill's metadata, directory structure, and configuration are correct.
Best Practices for Skill Publishing
Use descriptive names
A skill name should communicate its purpose without requiring extra context. booth-beacon-crawler is better than crawler because it tells users what the crawler targets. Names are globally unique on ClawHub, so a descriptive name also helps avoid collisions.
Keep your SKILL.md focused
Each skill should handle one category of work. If you find your SKILL.md describing unrelated tasks — weather queries and database operations in the same file — split it into multiple skills. Focused skills are easier to maintain and more likely to match user intent during automatic activation.
Include examples
The examples/ directory is not required, but it dramatically improves adoption. Show example inputs and expected outputs, or better yet, include a test command that users can run to verify the skill works:
# Add a test command to your SKILL.md: # Quick test: run `clawhub test my-awesome-skill` # to verify the skill loads and responds correctly.
Document dependencies
If your skill depends on external tools, API keys, or specific versions of OpenClaw, list them clearly in the configuration section. The most common publishing failure is a skill that works on the author's machine but fails for users because of undocumented assumptions about the environment.
Update regularly
Skills that are not updated for six months will have stale triggers, broken API integrations, and outdated usage patterns. Set a reminder to review your published skills quarterly. The cron scheduling guide shows how to set up automated reminders that can prompt you to check for skill updates.
Troubleshooting Common Publishing Issues
Publishing usually works on the first attempt, but when it does not, the errors are usually one of these patterns:
Validation error: missing SKILL.md — The CLI checks for a SKILL.md file in the root of your skill directory. Make sure the file exists and is not in a subdirectory. Case matters: skill.md will not be recognized.
Authentication error: invalid token — Run clawhub login again to refresh your API token. Tokens can expire if you generated them with an expiration date. Generate a new token from your ClawHub profile and retry.
Name conflict: skill already exists — Skill names are unique per publisher. If the name you chose is already taken by another publisher, choose a different name. If you previously published a skill and deleted it, the name may be reserved. Contact ClawHub support or use a variant of the name.
Size limit exceeded — Skills have a size cap to keep download times reasonable. Large binary files or dataset files should not be included in the skill directory. Instead, write a setup script that downloads the data at install time, or publish them separately. The multi-agent coordination guide shows patterns for splitting large workloads across multiple skills.
Managing Your Published Skills
After publishing, ClawHub provides commands for ongoing skill management. You can deprecate old versions, update metadata without a version bump, or withdraw a skill entirely:
# Update metadata without a version bump clawhub update my-awesome-skill --description "Updated description" # Deprecate an old version clawhub deprecate my-awesome-skill@1.0.0 "Use 2.0.0 instead" # List your published skills clawhub list --mine # Withdraw a skill (removes from search, keeps existing installs) clawhub withdraw my-awesome-skill
Withdrawing a skill is different from unpublishing. Withdrawn skills are not shown in search results but remain installable by users who already know the name. This prevents breaking existing workflows while making the skill invisible to new users.
From Local Skill to Ecosystem Contribution
Publishing your first skill to ClawHub transforms it from a personal automation into a community resource. The process is designed to be straightforward: structure your skill directory, write a clear SKILL.md, run clawhub publish, and keep it versioned as you iterate.
The best skills solve real problems clearly. They have focused triggers, explicit usage instructions, and documented dependencies. Users find them through search, install them with a single command, and integrate them into their OpenClaw environment without configuration headaches.
As the OpenClaw ecosystem grows, the quality of published skills becomes the difference between a platform that works out of the box and one that requires hours of tinkering. Every well-published skill raises the bar. If you have questions about the publishing process, the skills vs plugins comparison explains how skills fit into the broader OpenClaw architecture, and the MCP guide covers the protocol layer that skills often build on.