AgentKit
DocsKitsCLI ReferenceDesktop App
BetaYou are reading docs for the beta channel (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 --json

Options

FlagDefaultDescription
--name <@publisher/slug>None; requiredSkillX package name.
--version <semver>None; requiredRelease version, SemVer without build metadata.
--channel <channel>stableRelease channel: stable, beta or alpha.
--visibility <visibility>The SkillX default, privateVisibility of a new package: private, unlisted or public. It never changes an existing package.

Shared flags are described in CLI conventions.

Requirements

NeedDetail
SkillX onAfter ak update --ssot, or with AGENTKIT_SKILLX=1 or features.skillx: true. While off, the command exits 2.
A SkillX credentialThe 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.md at its root. The tree follows agentkit.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 --visibility names another. A publish never changes an existing package's visibility, so --visibility with a different value is refused (exit 6). Change it with ak 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 with ak 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

ExitMeaning
0Published, already published with the same content, or a replayed upload. A release stored as quarantined also exits 0; read state.
1Command failure: SkillX offline, the credential missing or refused, or an untrusted answer. The change may have been applied; check with ak skills visibility.
2SkillX disabled, invalid flags or arguments, a directory that is not a valid skill tree, or a request SkillX refused as invalid.
5Package not found, or release publishing not enabled on SkillX.
6Conflict with the package's current state: visibility mismatch, a version that already exists, or a publish to a deleted package.
7SkillX 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.