Publishing workflow

Publishing a skill follows one straight-line loop: scaffold it, check it, then ship it. SkillHub runs the safety checks for you and turns the result into an immutable version.

The loop

skillhub new tokens-workflow --type general
skillhub validate
skillhub scan
skillhub publish --to @studio/design-systems

You don't have to run validate and scan by hand — skillhub publish does both before it uploads. Running them separately just gives you faster feedback while you're still editing.

What publish does

When you run skillhub publish, it:

• Validates the skill against the spec.
• Scans it for security findings; a blocking finding stops the publish (exit 4) before uploading.
• Packs the directory into a content-hashed (sha256) tarball.
• Uploads it as a new immutable semver version and moves a dist-tag (latest by default, unless the registry requires review).

Every publish is a required type — one of project, general, or meta — carried in SKILL.md frontmatter. You can override it at publish time with --type.

Warnings are not failures

A blocking scan finding stops a publish. A structural warning — one of the benign content-length caps — does not: the server refuses the upload until the warnings are acknowledged, and the CLI prompts you to confirm them. Pass --allow-warnings (or --yes) to acknowledge up front in a script. The acknowledged warnings are recorded on the published version and come back in published[].warnings.

Choosing the target registry

A skill knows where it wants to go through the publishConfig in its manifest. You can override that from the command line with --to:

skillhub publish --to @studio/design-systems

The target is always a registry you can publish to — @owner/registry. If the manifest already names a target, --to wins for that run.

A skill skillhub installed already knows: the registry and the next version come from its lockfile entry, so publishing an edit back takes no flags at all. skillhub sync does the same across every store skill you've edited — see Publishing what you changed.

Single-dir versus bulk publish

Publishing one directory is promptless — it just runs:

skillhub publish

Passing multiple directories is the bulk path. Each skill is confirmed individually before it ships; add --yes to batch through the confirmations:

skillhub publish ~/.claude/skills/* --to @studio/design-systems --type general

Bulk publishing is handy for pushing a whole folder of skills into one registry. Note that --version can't be combined with a bulk publish — an exact version only makes sense for a single skill.

Reading the result

The published result reports each version and the tag that moved:

{
  "ok": true,
  "data": {
    "published": [
      { "ref": "@studio/design-systems/tokens-workflow", "version": "1.2.0", "tag": "latest", "scanStatus": "pass" }
    ],
    "skipped": []
  }
}

• version is the immutable semver version that was created.
• tag is the dist-tag that now points at it — or null if a review policy withheld the tag (see Review-required flow).
• scanStatus is pass, warn, fail, or pending.
• skipped lists directories whose per-skill confirmation you declined in a bulk publish.

Once the version is up, the skill gets a page in its registry — rendered SKILL.md, the install command, scan status, and the dist-tags that point at it:

Where to go next