3.2.0-beta.10). Features may change before the next stable release.Switch to stable →ak skills
ak skills publish
Publish a skill directory to SkillX as one immutable release of @publisher/slug; a new package is private unless --visibility names another.
Use ak skills publish to upload one skill directory to SkillX as a release of
@<publisher>/<slug> at an exact version. The command packs and checks the
tree locally and sends nothing until every check passes. It writes nothing
locally and never prompts.
Usage
ak skills publish <dir> --name <@publisher/slug> --version <semver> [flags]ak skills publish ./my-skill --name @alice/my-skill --version 1.0.0
ak skills publish ./my-skill --name @alice/my-skill --version 1.1.0-beta.1 --channel beta
ak skills publish ./my-skill --name @alice/my-skill --version 1.0.0 --visibility unlisted --jsonOptions
| Flag | Default | Description |
|---|---|---|
--name <@publisher/slug> | None; required | SkillX package name. |
--version <semver> | None; required | Release version, SemVer without build metadata. |
--channel <channel> | stable | Release channel: stable, beta or alpha. |
--visibility <visibility> | The SkillX default, private | Visibility of a new package: private, unlisted or public. It never changes an existing package. |
Shared flags are described in CLI conventions.
Requirements
| Need | Detail |
|---|---|
| SkillX on | After ak update --ssot, or with AGENTKIT_SKILLX=1 or features.skillx: true. While off, the command exits 2. |
| A SkillX credential | The upload uses the agentkit.best link (ak skills link) while one exists, otherwise SKILLX_TOKEN from ak secrets. A linked token needs the skillx-kits:write grant; an API key needs the releases:publish:@<publisher> scope. Without a credential nothing is sent. |
What it does
- The directory must hold
SKILL.mdat its root. The tree followsagentkit.skill-tree/v1: links are not followed, symlinks, devices and unsafe paths are refused before anything is sent, and VCS and OS metadata files are left out. SkillX takes at most 1000 files and 32 MiB. - A new package is private unless
--visibilitynames another. A publish never changes an existing package's visibility, so--visibilitywith a different value is refused (exit6). Change it withak skills visibility. - A version that already holds other content is refused (exit
6); publish a new version. A publish to a deleted package is refused too; bring the package back first withak skills restore. - The upload carries an idempotency key derived from the name, version, channel, visibility and the sha256 of the packed archive. A re-run after a lost answer replays the stored release instead of failing, and an upload SkillX is still storing under that key is retried with backoff.
- Where the platform does not record file modes (Windows), every file is published as non-executable, with a warning on stderr. Publish from macOS or Linux to keep executable scripts executable.
SkillX may store a release without publishing it: state quarantined while
its operators review the scan findings. The command still exits 0 and
prints a warning on stderr, so scripts must read state in the --json
output, not only the exit code.
Output
The text output names the outcome (Published,
Already published (same content) or Already published (replayed)), then
the visibility, channel, state, release digest, file count and packed size,
and one line per finding and warning. For a private package it also prints the
ak skills visibility <@publisher/slug> --set unlisted line that shares it.
JSON uses kind=skills.publish with these fields under data:
identity, version, channel, visibility, releaseDigest, artifactDigest,
state, created, replayed, files, archiveBytes, findings[], warnings[]Exit behavior
| Exit | Meaning |
|---|---|
0 | Published, already published with the same content, or a replayed upload. A release stored as quarantined also exits 0; read state. |
1 | Command failure: SkillX offline, the credential missing or refused, or an untrusted answer. The change may have been applied; check with ak skills visibility. |
2 | SkillX disabled, invalid flags or arguments, a directory that is not a valid skill tree, or a request SkillX refused as invalid. |
5 | Package not found, or release publishing not enabled on SkillX. |
6 | Conflict with the package's current state: visibility mismatch, a version that already exists, or a publish to a deleted package. |
7 | SkillX refused the change: approval needed on the SkillX dashboard, the credential's account does not own the publisher, the publisher is suspended, or an administrator deleted the package. |