publish#

Upload a skill directory to the registry. Requires authentication unless the server is running in dev mode.

Synopsis#

skillsctl publish --name NAME --version VERSION --description DESC --dir PATH \
  [--tag TAG ...] [--changelog TEXT]

Flags#

Required#

Flag	Description
`--name NAME`	Skill name. Must be unique in the registry. Use lowercase letters, numbers, and hyphens.
`--version VERSION`	Semantic version string, e.g. `1.0.0`.
`--description DESC`	Short description of what the skill does.
`--dir PATH`	Path to the skill directory to upload. Must contain `SKILL.md` at its root. The directory is packaged into a deterministic tar.gz before upload.

Optional#

Flag	Description
`--tag TAG`	Tag to apply to the skill. Can be repeated to add multiple tags.
`--changelog TEXT`	Release notes for this version.

Examples#

Publish a new skill:

skillsctl publish \
  --name git-conventional \
  --version 1.0.0 \
  --description "Enforce conventional commit messages" \
  --dir ./git-conventional

Published git-conventional@1.0.0

Publish with tags and a changelog:

skillsctl publish \
  --name git-conventional \
  --version 1.1.0 \
  --description "Enforce conventional commit messages" \
  --dir ./git-conventional \
  --tag git \
  --tag commits \
  --changelog "Add breaking change detection"

Published git-conventional@1.1.0

Version immutability#

Once a version is published, it cannot be overwritten. Publishing git-conventional@1.0.0 a second time returns an error. Increment the version number to publish an update.

Authentication#

On servers with OIDC configured, you must be logged in before publishing. Run skillsctl auth login first. Ownership of a skill is tied to your OIDC subject (not your email), so the same account must be used for all versions of a skill.

Common errors#

Error: version “X” already exists for skill “NAME” That version has already been published. Choose a new version number.

Error: missing SKILL.md at root of directory The directory passed to --dir must contain a SKILL.md file at its top level.

Error: packed size exceeds limit The tar.gz exceeds the server’s MaxPackedBytes limit (default 5 MB). Remove large files or split the skill into multiple skills.

Error: file too large An individual file in the directory exceeds the server’s MaxFileBytes limit (default 1 MB).

Error: unauthenticated The server requires a valid token. Run skillsctl auth login and try again.

Error: permission denied: skill owned by another user A different account published earlier versions of this skill. You cannot publish new versions for a skill you do not own.