Prepare Skillset Work for Publication

Separates workspace releases, downstream distribution planning, marketplace catalogs, and npm package publication.

Skillset has no general publish command. Choose the workflow that owns the thing you intend to ship:

A workspace release can refresh generated output, but it does not upload it to an external destination or prove runtime activation.

Release Workspace Source Units

Inspect source changes first:

skillset change status

If a changed source unit has no pending record, create one with the scope and release impact you intend:

skillset change add --scope skill:review-notes --bump patch --reason "Explain what readers of the review-notes skill will notice."

A reason must be at least 40 characters by default; change add accepts a shorter one, but release plan then fails with change-reason-too-short. Workspaces can change the minimum with changes.reason.minLength in skillset.yaml.

To revise an existing record, use the reference returned by change add or run skillset change list to find it, then replace the example @abcdef:

skillset change reason @abcdef --reason "Clarify which review-notes prompts changed and why it matters."

Both commands write source-side release evidence. Once the reasons and version impact are correct, preview and apply the release:

skillset release plan
skillset release apply --yes

The confirmed apply appends release evidence, advances source-unit version authority, refreshes generated changelogs, locks, and configured provider output, and consumes the pending changes included in the plan. It writes repository state; it does not publish over a network, install provider output, or change user-level runtime configuration.

Verify the result:

skillset release audit
skillset check

The Changes reference and Releases reference own the ledger, amendment, version, and changelog details. Exact commands live in the generated change and release pages.

Plan Downstream Distribution

Root distributions configuration selects an already enabled target rendering and describes a local or Git destination. Inspect every configured plan, or one named plan:

skillset distribute plan
skillset distribute plan codex-marketplace

Distribution is plan-only. The command does not accept --yes; it does not copy files, commit, push, open a pull request, or install runtime configuration. Local plans can report add, change, and unchanged; Git destinations remain unknown until a sync workflow is implemented to inspect them.

See Distributions for configuration, selection, and downstream ownership, and the generated distribute reference for command syntax.

Publish Individual Agent Skills

When Agent Skills is adopted, Skillset intrinsically renders each eligible standalone skill under .agents/skills/<skill>/. To make those standalone skills available from a Git repository, preview the build, confirm it, check the result, and then commit the generated skill directories and their nearby skillset.lock:

skillset build
skillset build --yes
skillset check

Bare skillset build only previews; no generated output is written until the --yes run.

A downstream consumer can then select one skill from the repository root. For example, the pinned Skills consumer used by this repository accepts:

npx skills add <repository> --skill <skill> --agent codex --copy --yes

Repository-root discovery is the preferred route. The pinned consumer finds the conventional .agents/skills tree before a valid manifest-resolved Claude duplicate and selects by the exact skill frontmatter name. Treat a root SKILL.md or same-name root skills/ entry as a conflict: the current consumer checks those locations first, and a root SKILL.md stops broader discovery. --full-depth broadens discovery into nested paths and should be reserved for repositories that intentionally need that wider scan. When a repository cannot remove a higher-priority conflict, scope discovery explicitly to <repository>/.agents/skills.

Plugin-owned skills are published as part of their canonical Agent Plugins package at plugins/<plugin>/skills/<skill>/. Skillset does not publish a second standard-owned copy under the repository .agents/skills/ root. A project-use copy is a separate projection with its own destination ownership; it is not part of individual Agent Skills publication.

Generation and consumer installation are separate actions. skillset build does not upload, publish, install, trust, or activate anything, and it does not change user-level configuration. If a repository previously exposed a Claude marketplace bundle as an interim individual-skill source, keep that native catalog correct and publish only the intended standalone .agents/skills tree alongside it; do not repoint the Claude catalog at a cross-provider path.

Publish the Compiler Package

This lane applies only to maintainers of the Skillset repository. Package-facing changes carry a .changeset/*.md entry, and the repository’s Release workflow versions and publishes the public npm packages after its policy gates pass: the unscoped skillset launcher, @skillset/cli, and the @skillset/native-* platform packages.

The safe local checks are:

bun run changeset:check
bun run publish:check

GitHub Actions is the package release operator. Do not run publish:packages locally as a normal workflow, and do not infer approval to merge or publish from a successful preflight. The maintainer-only Package Releases page owns package-facing paths, release labels, protected environments, trusted publishing, and recovery.

Workspace source-unit releases, npm package releases, distributions, and marketplace indexes remain separate evidence. Completing one lane does not complete or authorize another.