Building

Publishing

Drafts, immutable versions, private-first listing, yanking, and how installs follow updates.

The path from code to installs

Save draft  →  Publish x.y.z  →  (private: only your account)  →  List in Browse  →  anyone can install
                     ↑                                                    ↓
                  next version  ←───────────  installs on "Latest" follow (with consent for new access)

1. Create the plugin: Plugins → Created → New plugin — a name, a slug (lowercase letters, digits, hyphens) and a description. The slug is your plugin's permanent identity; tool names are prefixed with it.
2. Draft (optional): Save draft (⌘S) builds and validates exactly like a publish but takes no version number. Switch your own install to it with Use my draft to test on your account.
3. Publish a version: Publish… in the editor, or Publish from a .zip file instead with a version number.
4. List in Browse when you're ready for everyone: requires at least one published version.

What a publish does

In one step, all or nothing:

1. Checks every file fits the package format and requires a readme.md.
2. Bundles your code with esbuild into one readable script.
3. Runs it once to discover its capabilities and manifest; derives permissions from its host.* calls.
4. Validates the manifest, tools, commands, skills and companion assets.
5. Stores the version. A crash half-way leaves no half-visible version.

Any problem fails the publish with a message naming the file, key or line: "tool 'Lookup' must match ^[a-z][a-z0-9_]{0,63}$", "unknown globalThis.manifest key 'egres'", "the code calls host.fetch but declares no egress hosts", "a decision provider must implement modelProvider.noul, choose and score together".

If the platform is busy bundling other plugins you may get a retry shortly response — just publish again.

Versions

• A version is major.minor.patch, digits only (1.0.0, 1.4.12). The console's first publish is 1.0.0.
• Versions are immutable. Publishing the same number twice is refused. Fix forward with a new version.
• Installs on Latest follow the highest published version.

Use the numbers the usual way: patch for fixes, minor for additions, major for anything that breaks users — a renamed setting, a removed tool.

The version: key in readme.md (<major>.<minor> only) is used by the official-plugin pipeline, which picks the patch automatically: unchanged files publish nothing, changed files publish the next patch, a raised major.minor publishes <major>.<minor>.0, and a lowered one is refused. When you publish through the console or the API you choose the full number yourself.

Visibility

Remove from Browse takes it off the catalog: accounts that already installed it keep working on their version and see the optional message you write ("Why you're taking it down"). You can list it again later.

How installs follow your updates

Each install has a version policy:

New access waits for consent. If a new version asks for anything the owner hasn't agreed to — a permission, an egress host, an agent in manifest.agents — installs stay on the old version and show Update waiting for your OK, listing exactly what the new version adds. Nothing from the new version runs until they accept. A version that asks for the same or less moves silently.

On every version change your plugin receives events.pluginUpdated — see Lifecycle events.

Yanking

Pull a bad version with yank (on the version in the console, or the API). A yanked version stops being offered; you can't yank a plugin's last remaining version. To remove a plugin entirely, yank every version, then delete it — delete is disabled while a published version exists.

Official plugins

Plugins with the Official badge — Discord, Brave Search, Wiki Web, Caveman, Ponytail, My Dude — are published by AgentParley from its own repository as agentparley-<name>, through the same pipeline and the same SDK described here.

Checklist before you list

• The readme explains setup, every setting, and what the plugin reaches.
• npx tsc -p . passes against the downloaded SDK types.
• You tested the published version on your own account, including a fresh install.
• Lifecycle handlers are idempotent; middleware is fast; tool descriptions say when to use the tool.
• You call host.* literally (no aliases), so the permission list is complete.
• Nothing secret is stored in live-connection state or logged with host.log.