§02reading material

Publishing to AIpkgs

Five steps from local files to a registry-hosted package.

edition§02
classprimer / publish
revised2026-05-25
codexv0.1 · public draft

step 01

Create an account

No account, no publishing.

step 02

Get an organization

Every package is published under an org namespace.

Create one at /orgs/my.
Or get invited to an existing org by an admin.

Your published refs will look like <org>/<slug> or <org>/<key>/<slug>.

step 03

Set the ref in aipkg.json

Open aipkg.json in the package directory. Set ref to your org-scoped path and bump version.

{
  "type": "skill",
  "ref": "<org>/<slug>",
  "version": "0.1.0"
}

Keyed refs are allowed for sub-namespacing under your org:

{ "ref": "<org>/<key>/<slug>" }

The org segment must match an org you belong to. The registry rejects refs you don't own.

step 04

Login on the CLI

npx @aipkgs/cli login                           # opens an auth flow in the browser
npx @aipkgs/cli whoami                          # confirm the signed-in account

CI or headless? Set AIPKG_TOKEN=<token> instead.

step 05

Publish via the CLI

From the package directory:

npx @aipkgs/cli publish                         # publish the box in cwd
npx @aipkgs/cli publish ./packages/my-skill     # publish a different directory

The CLI reads aipkg.json, bundles the assets, and ships them to the registry under ref@version.

The registry rejects duplicate versions. Bump version in aipkg.json before every publish.

one page

Recap

# 01 · account        → create an account
# 02 · org            → create or join at an org
# 03 · ref            → set "ref": "<org>/<slug>" in aipkg.json
# 04 · login          → npx @aipkgs/cli login
# 05 · publish        → npx @aipkgs/cli publish