Author and publish APM packages

You’re here because you want to author an APM package others can install. This is the producer ramp.

Start a fresh package with apm plugin init; add a marketplace later with apm marketplace init. Two primitive postures cover most repos — ship your own plugin, or curate others into a marketplace — and they compose: one repo can do both at once. The five steps below tell you what to do between scaffolding and shipping.

The producer ladder

Five steps, in order. Each links to the page that owns it:

#	Step	What success looks like
1	Author primitives	Skills, prompts, instructions, agents, hooks, commands, MCP under .apm/
2	Compile your package	apm compile writes deterministic per-target output you can git-diff
3	Preview and validate	apm preview and apm view confirm what consumers will receive
4	Pack a bundle	apm pack produces a .tar.gz you can ship offline or to a marketplace
5	Publish to a marketplace	Others install your package with apm install <owner>/<repo>

You don’t need a marketplace to start. Step 4 is enough for internal teams; the marketplace step is for public discovery.

Where to start

Your situation	Start here
First time — want a working package end-to-end	Your first package
You have primitives in .apm/ and need to test them locally	Compile your package
You’re about to ship — want to verify what consumers will see	Preview and validate
You need to ship a single file to a customer / air-gapped env	Pack a bundle
You want a public marketplace listing	Publish to a marketplace
Your package links into other packages and you hit broken refs	Package-relative links

Production-grade releases

Once the 5-rung ladder works end to end, three pages cover the operational concerns of shipping at scale. They are independent of each other — pick what you need.

Concern	Page
Picking a repo layout before you author	Repo shapes — two starting layouts plus a hybrid composition for teams that ship their own plugin alongside a curated marketplace of others
Aligning versions across local packages	Versioning strategies
Wiring the release into any CI provider	Releasing from any CI

The producer mental model

A producer package is just a directory with:

my-package/
  apm.yml                    # manifest -- who you are, what you depend on
  .apm/
    skills/                  # primitives consumers can install
    prompts/
    instructions/
    agents/
    hooks/
  README.md                  # rendered on the marketplace listing

apm compile deterministically transforms .apm/ into per-target output. apm pack zips the result and, when an apm.yml declares a marketplace: block, writes the marketplace artifact alongside the bundle. Consumers reach it with apm marketplace add. There is no separate “build pipeline” — the CLI is the build pipeline.

Compatible with the consumer ramp

Every package you publish here installs through the consumer ramp’s apm install command. Test that loop yourself: install your own package in a scratch repo before declaring it shipped. The preview page walks you through the dry-run.