Skip to content
Agent Package Manager

Repo shapes for marketplace producers

A marketplace producer repo is just an apm.yml (or several) plus a marketplace: block. There is no --shape flag and no scaffold mode: every layout below emerges from the same two commands, apm plugin init and apm marketplace init, composed differently.

Two primitive postures cover most repos — you ship your own plugin, or you curate others’ plugins into a marketplace. The third row in the table is what happens when one repo does both at once. Pick the shape that matches how the source code is already organised; you can migrate later by moving directories and re-running the same commands.

ShapeSource filesWhen
Single-pluginOne apm.yml at the repo rootOne plugin per repo. Smallest surface, fewest gotchas.
AggregatorOne apm.yml at the root, N remote packages:You curate other repos into a marketplace.
Monorepo-hybrid (advanced)Root apm.yml plus per-plugin apm.yml subdirsMany plugins live alongside the marketplace in one repo. Composition of the two postures above.

When the layout is ready, ship it with the recipe in Releasing from any CI.

Single-plugin

Section titled “Single-plugin”

One repo, one plugin, one marketplace entry pointing at the local source. The marketplace artifact and the plugin live side by side.

Scaffold:

Terminal window
apm plugin init my-plugin --yes
apm marketplace init --owner acme-org --name my-marketplace
apm marketplace package add ./ --name my-plugin --version 0.1.0

Resulting apm.yml:

name: my-plugin
version: 0.1.0
description: Single plugin shipped through its own marketplace


marketplace:
  owner:
    name: acme-org
    url: https://github.com/acme-org
  outputs:
    claude: {}
  packages:
    - name: my-plugin
      source: ./
      version: 0.1.0

apm pack writes the plugin bundle to ./build/my-plugin/ and the marketplace artifact to .claude-plugin/marketplace.json. Commit both. Consumers run apm marketplace add acme-org/<repo>.

Aggregator

Section titled “Aggregator”

One repo whose only job is to curate plugins that live in other repos. No plugin source lives here.

Scaffold:

Terminal window
apm marketplace init --owner acme-org --name acme-curated
apm marketplace package add acme-org/skill-pkg-a --version "^1.0.0"
apm marketplace package add acme-org/skill-pkg-b --ref v0.4.2

Resulting apm.yml:

name: acme-curated
version: 1.0.0
description: Curated APM marketplace for acme-org


marketplace:
  owner:
    name: acme-org
    url: https://github.com/acme-org
  outputs:
    claude: {}
  packages:
    - name: skill-pkg-a
      source: acme-org/skill-pkg-a
      version: "^1.0.0"
    - name: skill-pkg-b
      source: acme-org/skill-pkg-b
      ref: v0.4.2

apm pack resolves every remote entry against git ls-remote and writes marketplace.json only. No bundle is produced because there is no dependencies: block.

Monorepo-hybrid

Section titled “Monorepo-hybrid”

Advanced. Most first-time authors should start with single-plugin or aggregator. Reach for hybrid when you’re shipping your own plugin and curating others. DevExpGbb/zava-agent-config is the live reference: 7 plugins under plugins/, one root apm.yml, releases via microsoft/apm-action@v1 mode: release.

One repo, many plugins under packages/, one marketplace at the root that lists them as local-path entries. Each plugin gets its own apm.yml so it can be compiled and tested in isolation.

Layout:

my-monorepo/
  apm.yml                          # marketplace + local-path packages
  packages/
    plugin-a/
      apm.yml                      # plugin-a's manifest
      .apm/
    plugin-b/
      apm.yml
      .apm/

Scaffold:

Terminal window
apm plugin init plugin-a --yes              # cd packages/plugin-a first
apm plugin init plugin-b --yes              # cd packages/plugin-b first
cd ../..
apm marketplace init --owner acme-org --name acme-monorepo
apm marketplace package add ./packages/plugin-a --name plugin-a
apm marketplace package add ./packages/plugin-b --name plugin-b

Resulting root apm.yml:

name: acme-monorepo
version: 1.0.0
description: Acme plugins shipped together


marketplace:
  owner:
    name: acme-org
    url: https://github.com/acme-org
  outputs:
    claude: {}
  versioning:
    strategy: lockstep              # see versioning-strategies
  packages:
    - name: plugin-a
      source: ./packages/plugin-a
      version: 1.0.0
    - name: plugin-b
      source: ./packages/plugin-b
      version: 1.0.0

Local-path entries skip remote resolution. Each plugin’s own apm.yml controls its build; the root apm.yml controls the marketplace index. Pick a versioning strategy that matches how you tag releases — see Versioning strategies.

Section titled “What to read next”