Publish & Install

Connect a GitHub repo, publish your plugins to it, and install them in Claude Code

Publishing takes your marketplace’s committed content and writes it into a GitHub repository, one-way. That repo is the installable marketplace — you and your users add it in Claude Code and install plugins from it. Publishing is a deliberate release step, distinct from the dev loop, which never touches GitHub.

Step 1: Connect a GitHub repository

A marketplace publishes to exactly one GitHub repo. Connecting is a link — it points your marketplace at the repo as a publish target. It does not import the repo’s existing contents, so a fresh empty repo is the cleanest choice.

In the Moxn web app, open your marketplace and choose Connect GitHub Repository:

1. Authorize the Moxn GitHub App

   A one-time authorization grants Moxn permission to write to repositories you select. You control exactly which repos it can access.

2. Pick the account and repository

   Choose the installation (personal or org) and the target repo.

Once connected, the marketplace is linked as a publish target — nothing is written yet.

Agents can connect via marketplaces { action: "connect", marketplaceId, installationId, owner, repo } after the one-time App install. marketplaces { action: "installations" } lists what is reachable.

Step 2: Commit — which is publishing

There is no separate publish step. Committing writes to GitHub:

marketplaces { action: "commit", marketplaceId: "<uuid>", ref: "main", message: "Ship the greet skill" }

With no writes, this publishes whatever is currently drafted — which is what you want after an edit. Drafts live only in Moxn until this point, so a half-finished change cannot leak to your users.

That “whatever” is branch-wide: it includes drafts other sessions left behind. Read draftPaths from tree on the same ref before committing without writes, or name the files explicitly — see Create & Author.

Each commit also:

• flattens pending suggestions to their accepted text and strips every comment marker, so published files never contain review markup;
• regenerates the Codex and Cursor manifests from your Claude-layout content, so the repo stays installable on all three;
• is compare-and-swapped against the branch head. If someone else pushed in the meantime, you get a conflict decision list (keep_mine / take_theirs / supply_merged / commit_to_new_branch) rather than an error — resubmit with a decision.

Committing to the default branch is publishing to everyone who has the plugin installed. To get review first, commit to a branch and open a pull request — see Create & author.

Knowing where things stand

• marketplaces { action: "status", branch } — how far a branch is ahead of / behind the default branch.
• marketplaces { action: "history", ref, paths } — published commits, newest first, for a branch or a single file. Read live from GitHub, so a commit someone pushed from their laptop is in it. This is the only history there is: an uncommitted draft has never been a commit and never appears.
• marketplaces { action: "pre_merge_report", branch } — advisory findings before a merge.

Step 3: Install in Claude Code

Your published repo is a standard Claude Code plugin marketplace. Add it, then install a plugin from it:

/plugin marketplace add <owner>/<repo>
/plugin install <plugin>@<marketplace>

For example, for the localization plugin in a marketplace published to acme/plugins:

/plugin marketplace add acme/plugins
/plugin install localization@acme-plugins

The plugin’s skills, commands, and agents are now available in the session (run /reload-plugins or restart if they don’t appear immediately). This is the same repo anyone you share it with can install from.

Installing in Codex

The same published repo installs in Codex — Moxn generates the Codex manifests (.agents/plugins/marketplace.json and per-plugin .codex-plugin/plugin.json) alongside the Claude Code ones on every publish:

codex plugin marketplace add <owner>/<repo>
codex plugin add <plugin>@<marketplace>

Your plugin’s skills load in Codex sessions just like any official plugin — the SKILL.md contract (name + description) is shared across both harnesses. Commands and agents are Claude Code concepts today; Codex ignores them.

Plugin version and description

codex plugin list shows each plugin’s version, read from its .codex-plugin/plugin.json. Set your plugin’s version and description in Moxn — they’re plugin-level metadata, distinct from any component’s frontmatter:

The plugin manifest is a file like any other, so you edit it the way you edit a skill:

marketplaces {
  action: "edit",
  marketplaceId: "<uuid>",
  writes: [{
    path: "plugins/localization/.claude-plugin/plugin.json",
    contents: "{\n  \"name\": \"localization\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Translation and localization tools\"\n}\n"
  }]
}

Edit the Claude manifest only. .codex-plugin/plugin.json is regenerated from it on every commit — hand-edit it and your next commit overwrites you.

Codex decides staleness from the version string alone, so a content change without a bump would be invisible to Codex users forever. Moxn defends against that by stamping a content-derived cachebuster into the generated Codex manifest — 0.1.0+codex.<sha7> — which changes whenever your content does, whether or not you bump.

To ship an update to Codex users: publish, then they run codex plugin marketplace upgrade <marketplace>.

Installing in Cursor

The same repo also installs in Cursor (2.5+), which has its own plugin marketplace system — Moxn generates the Cursor manifests (root .cursor-plugin/marketplace.json and per-plugin .cursor-plugin/plugin.json) on every publish:

1. Add the marketplace: in the Cursor app, use /add-plugin (or Settings → Customize → Plugins) with your repo URL — or from the Cursor CLI: cursor-agent plugin marketplace add https://github.com/<owner>/<repo>.
2. Install the plugin: pick it from the marketplace listing (in-app, or cursor-agent → /plugin → Marketplace tab). Cursor has no non-interactive install command yet, so this step is interactive.

Your skills load and fire in Cursor sessions — the same shared SKILL.md contract. Your agents use Cursor’s subagent format (markdown + name/description frontmatter), and the plugin’s version and description appear in Cursor’s listing the same way they do in Codex.

Updating a published plugin

Consumers install a pinned version — they don’t drift as you keep working. To ship an update:

1. Edit and commit in Moxn

   Make your changes and commit them. The commit is the publish.

2. Consumers update — BOTH steps

   claude plugin marketplace update <marketplace>
   claude plugin update <plugin>@<marketplace>
   

   Then /reload-plugins in an open session, or start a new one.

   The first command alone is not enough, and it looks like it worked. It advances the marketplace clone and writes the new commit’s files to disk, printing success — but the install pointer still names the previous commit, so sessions keep loading the old skill body while the files on disk show the new one.

   context marketplaces refresh --marketplace <name> --plugin <name> runs both.

Iterating on the plugin yourself? Don’t publish for every change — use the dev loop to test against your live Moxn branch, and publish only when you’re ready to release.