how to publish a skill on clawhub

I published my first ClawHub skill on a Thursday afternoon. The whole thing took about 20 minutes, and most of that was me second-guessing my manifest metadata. The actual publishing step? One command.

But getting to that one command requires knowing what ClawHub expects, how the CLI authenticates, and what causes silent rejections. This guide covers the full path from zero to a live, searchable skill in the registry.

What is ClawHub?#

ClawHub is the public skill registry for OpenClaw agents. Think of it as a package registry (like npm) but specifically for agent skills. It uses vector search to index skills, so discoverability depends heavily on how you write your manifest and SKILL.md file. When someone runs openclaw skill install your-skill, it pulls from ClawHub.

The clawhub CLI handles publishing and syncing. The openclaw CLI handles installation. Two separate tools, two separate concerns.

How to publish a skill on ClawHub (step-by-step)#

1. Create a GitHub account at least one week old.
2. Sign up for a developer account at clawhub.ai.
3. Structure your skill directory with a valid SKILL.md and manifest.
4. Install the clawhub CLI and authenticate with clawhub auth login.
5. Run clawhub publish <path> from your skill root.
6. Add version tags with clawhub tag <skill> <version> latest.
7. Verify your skill is live at clawhub.ai/skills/your-skill-name.

Each step has nuances worth understanding. Let me walk through them.

Prerequisites before you start#

You need a GitHub account that's at least seven days old. ClawHub uses GitHub OAuth for identity verification, and new accounts are rate-limited as a spam prevention measure. If you created your GitHub account yesterday, wait.

You also need Node.js 18+ installed (for the CLI) and a working OpenClaw environment if you want to test your skill locally before publishing.

Setting up your developer account#

Head to clawhub.ai and click "Sign up as developer." You'll authorize via GitHub OAuth. Once authenticated, ClawHub creates a namespace tied to your GitHub username. This namespace is permanent, so if your GitHub handle is cool-agent-builder, your skills will live under that prefix.

After signup, you'll see a dashboard showing your published skills (empty for now), install counts, and API token management. You won't need the API token for basic publishing since the CLI handles auth through the OAuth flow.

Structuring your skill directory#

ClawHub expects a specific directory layout. At minimum:

my-skill/ ├── SKILL.md # Required: description, usage examples, metadata ├── manifest.json # Required: permissions, dependencies, entry points ├── index.ts # Your skill's entry point └── README.md # Optional but helps discoverability The SKILL.md file is required. Without it, clawhub publish will reject your submission. This file follows a structured format:

---
name: my-cool-skill
version: 1.0.0
description: "One-line description of what this skill does"
author: your-github-username
tags: ["email", "automation", "api"]
permissions:
  - network
  - filesystem:read
---

# My Cool Skill

Extended description, usage examples, and configuration docs.

The frontmatter in SKILL.md is what ClawHub's vector search indexes. Your description and tags fields directly affect whether people find your skill when searching. Be specific. "Sends emails" is worse than "Provisions disposable email inboxes for agent verification workflows."

The manifest.json file#

Your manifest declares what your skill needs at runtime:

{
  "name": "my-cool-skill",
  "version": "1.0.0",
  "entry": "index.ts",
  "permissions": ["network"],
  "dependencies": {
    "@lobsterkit/lobstermail": "^1.0.0"
  },
  "runtime": {
    "timeout": 30000,
    "memory": "256mb"
  }
}

The permissions array is where most rejections happen. ClawHub reviewers (automated + manual for popular skills) flag overly broad permissions. If your skill only makes HTTP requests, don't request filesystem:write. Request exactly what you need and nothing more.

For skills that interact with outbound messaging infrastructure (email delivery, webhooks, external APIs), declare those dependencies explicitly in the manifest. Reviewers check that declared permissions match actual usage. A skill that sends emails but doesn't declare network permission will fail silently after installation because the sandbox blocks the outbound call.

Installing and authenticating the CLI#

npm install -g @clawhub/cli
clawhub auth login

The auth login command opens a browser window for GitHub OAuth. Once authorized, the CLI stores credentials locally. You can verify with:

clawhub whoami

This should print your GitHub username and namespace.

Publishing your skill#

From your skill's root directory:

clawhub publish .

That's it. The CLI validates your SKILL.md, checks the manifest, bundles your files, and uploads to the registry. If validation fails, you'll get specific error messages pointing to the issue.

Common validation failures:

• Missing SKILL.md frontmatter fields (name, version, description are required)
• Version conflicts (you can't republish an existing version number)
• Permission mismatches between manifest.json and SKILL.md
• Files exceeding the 10MB package size limit

After a successful publish, your skill is searchable within 2-3 minutes as the vector index updates.

Tagging and versioning#

ClawHub uses semver with a tag system similar to Docker or npm. After publishing version 1.0.0:

clawhub tag my-cool-skill 1.0.0 latest

The latest tag is what users get by default when they run openclaw skill install my-cool-skill. Without tagging, your published version exists but isn't the default install target.

To publish an update, bump the version in both SKILL.md and manifest.json, then run clawhub publish . again. The old version remains available (users can pin specific versions), but you'll want to move the latest tag:

clawhub tag my-cool-skill 1.1.0 latest

Rolling back a bad release#

If you ship a broken version:

clawhub tag my-cool-skill 1.0.0 latest

Just point latest back to the working version. The broken version stays in the registry (you can't truly delete published versions for dependency stability), but no one installs it by default.

If you need to actively delist a version:

clawhub unpublish my-cool-skill@1.1.0

This marks the version as deprecated. Existing installations keep working, but new installs are blocked.

Testing locally before publishing#

Always test before publishing. The clawhub inspect command validates without uploading:

clawhub inspect .

This runs the same validation pipeline as publish but stops before upload. It checks manifest structure, permission declarations, SKILL.md format, and file size limits.

For functional testing, use OpenClaw's local skill loading:

openclaw skill load ./my-skill

This mounts your skill locally so you can invoke it through your agent without publishing to the registry first.

Keeping your skill in sync with source#

If your skill lives in a Git repository (it should), you can automate publishing on merge. Add a GitHub Action:

name: Publish to ClawHub
on:
  push:
    branches: [main]
    paths: ['skills/my-skill/**']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @clawhub/cli
      - run: clawhub auth token ${{ secrets.CLAWHUB_TOKEN }}
      - run: clawhub publish skills/my-skill
      - run: clawhub tag my-skill $(jq -r .version skills/my-skill/manifest.json) latest

Generate a CI token from your ClawHub dashboard under Settings > API Tokens. This token has publish-only scope, so even if it leaks, it can't delete or modify existing versions.

Credentials and secrets in published skills#

Your published skill will run in other people's agent environments. Never hardcode API keys or tokens in your skill code. Instead, declare required credentials in your manifest:

{
  "credentials": {
    "LOBSTERMAIL_TOKEN": {
      "description": "LobsterMail API token for email operations",
      "required": true
    }
  }
}

When someone installs your skill, OpenClaw prompts them to provide the required credentials. These are injected at runtime through environment variables, never stored in the skill package itself.

If your skill needs email capabilities (sending verification codes, receiving webhooks, forwarding messages), the cleanest approach is to let the installing agent provision its own inbox. With LobsterMail, the agent can self-provision without human signup, so your skill doesn't need to bundle any pre-configured email infrastructure. If you want your agent handling its own email setup, grab an inbox here and the agent takes care of the rest.

Monitoring after launch#

ClawHub's dashboard shows install counts, but that's about it for built-in analytics. For error monitoring, add structured logging to your skill and document that users should check their agent logs if something breaks.

Watch your GitHub issues. Users who install from ClawHub tend to file bugs on the source repository rather than through the registry itself.