Skip to main content

Publish a skill

Version and publish a skill to the AgentXM.ai registry with the visibility and access your consumers need.

Once you've created a skill and used it locally, two commands share it: bump the version, then publish. AXM validates the skill before it leaves your machine. Registry visibility and access determine who can install the published version.

Before you publish

Section titled Before you publish

This workflow publishes the workspace-authored package in skills/<name>/ — the skill.json manifest and its src/SKILL.md. Workspace selectors do not publish acquired packages under agent_extensions/. Make sure the skill is complete:

  • The skill.json manifest names an owner and the metadata the registry records.
  • The SKILL.md has a name and a description that says plainly what the skill does and when to use it; the agent host controls activation.

You also need an AgentXM.ai account and a handle to publish under. That platform side — accounts, handles, and visibility — lives on agentxm.ai; see The platform side below.

Bump the version

Section titled Bump the version

Every published release needs a version. Bump it with axm version:

axm version @owner/skills/code-review minor

The bump rule is a positional argument — patch for fixes, minor for additive changes, and major for breaking ones. See live command help for other rules. This updates the version in skill.json following semantic versioning. The registry treats versions as immutable: once a version is published, you can't overwrite it, so each release gets a fresh number.

Publish

Section titled Publish

Preview and publish the exact skill with axm publish:

axm publish @owner/skills/code-review --preview
axm publish @owner/skills/code-review

Before uploading anything, AXM validates the release:

  • It checks the skill.json manifest against the skill schema.
  • It checks the SKILL.md frontmatter (name, description) and structure.
  • An already-published version is skipped successfully; its immutable bytes are not overwritten. Publish a new version for changed content.
  • An unpublished version below the highest published version requires the explicit --backfill option.
  • It preflights the complete selected set before the first upload. A selected pack must be able to resolve every dependency from the effective post-selection Registry state, and a locally authored pack may not exclude a selected local member version unless the same coordinated selection repairs the range.

Preflight may also report compatibility-review warnings. Review them before accepting them with --accept-warnings. For example, an officially paired pack may not yet include the new member version, or a locally authored pack may resolve a different member version than Registry consumers. Human output shows the warning and its suggested AXM action; --json preserves the structured action for automation.

If validation passes and any reported warnings are accepted, AXM uploads the release. Public versions can be installed publicly; private versions require authorized access. For a new extension, choose initial visibility with --visibility public or --visibility private. Authorized consumers install it by its published owner:

axm skills install @your-handle/skills/code-review

For the full set of flags — previews, visibility, and selection — see the axm skills publish reference.

The platform side

Section titled The platform side

Publishing writes to the AgentXM.ai registry, and the account-level concerns live there, not in the CLI:

  • Accounts — sign in on agentxm.ai to get the credentials AXM publishes with.
  • Handles — your handle is the owner segment in @your-handle/skills/code-review. Claim and manage it on agentxm.ai.
  • Visibility — whether a published skill is public or restricted, and who can install it, is governed on agentxm.ai.

The CLI is the publishing path; agentxm.ai is where you manage what you've published and who can see it.

Publishing other extension types

Section titled Publishing other extension types

The same two-step flow — version, then publish — applies to every extension type AXM manages. Use the shared axm version <fqn> <patch|minor|major> command to bump a manifest, then publish through the type-specific command family:

Validation, immutable versions, existing-version skips, and backfill rules apply across all of them. Skills are the concrete starting point; once you've published one, you've published them all.

Operational source: axm help publish and axm publish --help for your installed CLI. This walkthrough was reconciled with AXM 0.51.0.

See also

Section titled See also