Publish your first package

By the end of this guide you will have a published skill package on the APKG registry. The whole process takes about five minutes.

Prerequisites

• APKG CLI installed — see Installation if you haven’t set it up yet.
• An APKG registry account — sign up at apkg.ai if you don’t have one.

Log in to the registry

Authenticate so the CLI can publish on your behalf:

apkg login

You will be prompted for your username, password, and — if enabled — a multi-factor authentication code.

Verify you are logged in:

apkg whoami

You should see Logged in as <your-username>. See apkg login for details on credential storage and private registries.

Create your package

Create a new directory and initialize it:

mkdir my-skill && cd my-skill
apkg init

The interactive wizard walks you through each field:

Prompt	What to enter	Default
Package name	@<username>/my-skill	@<username>/<directory>
Version	0.1.0	0.1.0
Package type	skill	skill
Description	A short summary of what the skill does	(empty)
License	MIT	MIT
Keywords	Comma-separated tags	(empty)

The name must be scoped — @username/name or @org/name. If you are logged in, the wizard defaults to your username as the scope.

After answering the prompts, apkg init writes an apkg.json like this:

{
  "name": "@alice/my-skill",
  "version": "0.1.0",
  "type": "skill",
  "description": "A useful skill that reviews code",
  "license": "MIT",
  "keywords": ["code-review"]
}

Add your package files

A skill package needs at least one .md definition file (besides README.md) so that AI coding tools know what the skill does. Create a file — for example code-reviewer.md:

---
name: code-reviewer
description: Reviews code for bugs and quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. When asked to review code, analyze it for:

- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Readability improvements

Provide clear, actionable feedback.

The YAML frontmatter declares the skill’s name, description, and which tools it needs. The body is the prompt that the AI assistant will use.

You can also add a README.md with a longer description for humans — apkg init automatically sets the readme field if the file exists.

Publish

Run the publish command from your package directory:

apkg publish

On success you will see the published package name, version, size, and integrity hash. The CLI checks that your package scope matches your logged-in username — if it doesn’t (for example, you’re publishing under an organization), a warning is shown, but publishing still succeeds if you are a member of that organization.

Verify your package

Confirm your package is live on the registry:

apkg info @alice/my-skill

You can also search for it:

apkg search my-skill

Next steps

• Package Types — The workflow is the same for agent, command, and rule packages — only the manifest type and content files differ.
• apkg publish — Full reference for publish options and metadata.
• dist-tag — Tag versions as latest, beta, or any custom label.
• key — Sign packages with Ed25519 keys for provenance verification.
• token — Create API tokens for CI/CD pipelines so you can publish without interactive login.
• CLI Reference — Complete reference for all commands.