# 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](/docs/create-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

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](https://agentxm.ai) account and a handle to
publish under. That platform side — accounts, handles, and visibility — lives on
agentxm.ai; see [The platform side](#the-platform-side) below.

## Bump the version

Every published release needs a version. Bump it with
[`axm version`](/docs/cli-reference/version):

```bash
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

Preview and publish the exact skill with
[`axm publish`](/docs/cli-reference/publish):

```bash
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](https://axm.sh/schemas/skill.schema.json).
- 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:

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

For the full set of flags — previews, visibility, and selection — see the
[`axm skills publish`](/docs/cli-reference/skills/publish) reference.

## The platform side

Publishing writes to the [AgentXM.ai](https://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

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:

- `axm subagents publish` for [subagents](/docs/subagents)
- `axm hooks publish` for [hooks](/docs/hooks)
- `axm knowledge publish` for [Knowledge](/docs/knowledge)
- `axm packs publish` for [packs](/docs/packs)

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

- [Create a skill](/docs/create-a-skill) — author a skill before you publish it
- [Find and install skills](/docs/find-and-install-skills) — the other side of
  publishing
- [Skills](/docs/skills) — what a skill is and how AXM manages it
- [Set up your team](/docs/set-up-your-team) — share extensions across a repo
- [`axm version`](/docs/cli-reference/version) and
  [`axm skills publish`](/docs/cli-reference/skills/publish) — full CLI
  reference