ClawHub Publishing Workflow

Most publishing mistakes are not dramatic. They are boring. Wrong owner. Missing metadata. A skill that reads one env var but declares another. A plugin package with the wrong scope. Then people wonder why the release did not show up where they expected.

The short version: ClawHub publishing is a validation pipeline, not a dumb file upload. It checks who you are publishing as, what you are uploading, whether the metadata is believable, and whether the release should be visible yet.

What the publishing flow is actually doing

The official ClawHub publishing docs describe a flow where ClawHub validates owner access, package identity, version, files, and source information before storing the release and starting automated security checks. If validation fails, nothing gets published. If validation passes, the release can still stay out of normal install surfaces until review finishes.

That is why publishing feels less like dragging a file into Dropbox and more like shipping a parcel internationally. The label, sender, contents, and paperwork all need to line up.

Skills and plugins follow different lanes

This is the first split to get right. A skill is a folder centered around SKILL.md. A plugin is a package with plugin-specific metadata and compatibility fields. Same registry, different shape.

If you blur those two lanes, confusion starts early and gets expensive fast.

The practical publish sequence

If you want a clean workflow, think in four stages: sign in, inspect, dry-run, then publish.

1. Sign in so the CLI knows which user or org context you can publish under.
2. Inspect the package shape before touching the registry.
3. Run dry-run to preview what ClawHub thinks you are about to publish.
4. Publish for real only after the preview looks boring.

Boring is good here. Publishing should feel uneventful when the metadata is healthy.

Skill workflow

clawhub login
clawhub sync --dry-run --owner <owner>
clawhub sync --all --owner <owner>

According to the docs, sync scans for folders containing SKILL.md, compares them with ClawHub, and publishes the new or changed ones when you drop the dry-run flag.

Plugin workflow

clawhub package publish <source> --family code-plugin --dry-run
clawhub package publish <source> --family code-plugin

That preview step matters more than people think. It lets you confirm compatibility fields, source attribution, and upload plan before you mint a real release.

What metadata matters most for skills

The official skill format docs make one thing very clear: the registry is not only reading your prose. It is extracting runtime expectations from your frontmatter.

• description: the summary users see in the UI and search
• metadata.openclaw.requires.env: env vars the skill truly cannot run without
• envVars: richer per-variable declarations, including optional variables
• requires.bins and install specs: what needs to exist on the machine
• homepage and supporting files: useful context for trust and review

This is where a lot of beginners quietly sabotage themselves. They treat SKILL.md like marketing copy. ClawHub treats it more like a manifest. If your manifest lies, the rest of the trip gets awkward.

---
name: my-skill
description: Short summary of what this skill does.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
    envVars:
      - name: TODOIST_API_KEY
        required: true
        description: Todoist API token.
---

Think of this block as the customs declaration for your skill. It tells ClawHub what is inside and what the skill will ask from the system once installed.

The plugin trap: owner and scope must match

Plugin publishing has its own classic faceplant. Package scopes are not decoration. They are ownership claims.

If your package is named @openclaw/dronzer, you need publish access for the @openclaw owner. If you only control another owner, rename the package to match that scope before publishing. ClawHub rejects scope-owner mismatches on purpose.

This is a good guardrail, not bureaucracy. Without it, anyone could try to publish into an org namespace they do not actually control.

Common publishing mistakes

1. Skipping dry-run because the folder “looks fine”

That is how avoidable issues survive until release time. Dry-run is your cheap rehearsal. Use it.

2. Declaring metadata that does not match reality

If the skill reads env vars or binaries that never appear in frontmatter, review gets messy and user trust drops. Honest metadata is part of the product, not paperwork after the product.

3. Publishing to the wrong owner

This hits org repos a lot. The authenticated user may exist, but that does not mean they are publishing under the correct owner handle.

4. Forgetting that visibility can lag behind upload

A release may exist and still not appear in normal install or search surfaces yet. That does not automatically mean the publish failed. It may still be moving through checks.

Dry-run is not optional if you care about your future self

There is a nice old carpenter rule: measure twice, cut once. ClawHub dry-run is the registry version of that. It is not glamorous, but it saves you from turning a private mistake into a public one.

Especially for catalog repos, dry-run gives you something more valuable than reassurance. It gives you a reviewable plan. That means teammates can sanity-check owner choice, skill path, and metadata before the publish button stops being hypothetical.

A simple decision rule

• Publishing one or more skills? Start with clawhub sync --dry-run.
• Publishing a plugin package? Start with clawhub package publish ... --dry-run.
• Unsure whether the metadata is accurate? Fix that before you publish anything.

📌 Action step

→ open your skill or plugin folder and check the metadata like an auditor, not like a proud parent.
→ run the dry-run command first and read the output slowly.
→ only publish once the owner, scope, version, and runtime requirements all agree with each other.