On distribution

[mekza]

Disclaimer: I work at AWS and I started ARA and its internal implementation, code-named Holocron. I am not neutral about whether distribution deserves its own layer.

The idea of this discussion is to aggregate the distribution discussions as I see 3 open threads all talking about distribution:

• Add dependencies field to plugin manifest #51 wants a dependencies field in the manifest, resolved from git URLs and refs.
• Define a marketplace/registry index format #52 wants a marketplace.json index so a repo can list the plugins it hosts.
• Roadmap beyond skills + MCP? #35 asks for dependency resolution, signing and marketplaces on the roadmap, and notes that plugins are not installable standalone in Codex CLI without a proprietary marketplace format.

v1 of the spec left this out on purpose: "distribution, installation, permissions, UX and client-specific capabilities stay under each client's control" but now that there is a vendor-neutral spec defining the artifact, it seems like the right time to discuss how artifacts get distributed and governed.

In May 2025 a few of us at Amazon ran an experiment. AI usage was booming, people were creating more and more artifacts, and distribution quickly became the bottleneck, artifacts moved by Slack message, zip file and wiki page. The most common question about an artifact was "is this the latest version?" So we built a boring package manager (API+CLI), with a manifest, lockfile, registry, semver and integrity hashes. We did not invent much, we got our inspiration from (read: copy) npm, Cargo and pip, on the theory that if npm, Cargo and pip all converged on the same design, it is probably the right one.

Fast-forwarding to January 2026, we already had multiple thousands of builders and published artifacts. That convinced us the problem was not Amazon-specific, so in February 2026 we open-sourced the spec as ARA or AI Registry for Agents. We split it in two: one spec for the artifact, one for distribution (API). Now we are actively exploring dropping our own artifact format ara.json in favour of plugin.json and focus on the distribution only.

What we learned building this is that a registry is mostly the unglamorous parts: fine-grained access control, namespace ownership so nobody can publish under your name, security scanning on publish, integrity verification on install, immutable versions, audit trails, private visibility, and private registries for organisations that cannot use a public one. Plus real dependency resolution, meaning a solver rather than an install order, and a clear answer for what happens when a dependency is missing. I do not think any of these belongs in a packaging spec. We also talked to few enterprises and this is what they ask for before they let a few thousand developers install plugins.

Now on the discussions:

On #51 : a git ref is not a version. If a tag moves, two people who pinned v2.1.0 get different bytes. And there is no way to say "any 2.x is fine", so every upgrade means editing every dependent by hand.

On #35 : the spec never says where plugins live. §11.1 says a client can load a plugin from a directory path, and §4.1 defines the plugin root, but nothing says which directory. So each client picks its own, and each has its own setup instructions. Any installer then has to learn all of them. That is the same fragmentation the homepage describes for packages, one level down.

One more thing on #51 : It rejects extensions as "spec-conformant but not portable across clients". Agreed for dependencies: if every client needs a field, it belongs in core.

Registry metadata is the opposite case. Where an artifact came from, its hashes, whether it can be published publicly: no client needs any of that, only a registry does. So extensions looks like a good home for it.

One question then: §8 is called "Client extensions", and §3 says a Client "discovers, installs, loads, and executes". A registry only does the first two. Is extensions open to distribution tooling too, or only to clients?

Is distribution in scope for a future Agent Plugins version, or should it stay outside and compose, as a separate spec, the way OCI splits image-spec from distribution-spec? I'd go the 2 specs route, because it makes things decoupled and you can imagine existing registries to also support multiple package types. That is the bet we are making by dropping our own artifact format and putting our registry metadata in an extension namespace. Happy to go deeper on integrity, deps resolution or namespace ownership if that is useful when the FUTURE_CONSIDERATIONS.md items come up.