Create & Author

Create a marketplace, connect a repo, and write your skills, commands, and agents in Moxn

A marketplace is a GitHub repository with plugins in it. Moxn gives you a working surface over that repo — branches, drafts, comments, review — and publishes to it when you commit.

Everything below is exposed by the Moxn marketplaces MCP tool, so an agent connected to Moxn can do it directly, and the same operations exist in the Moxn web app and the context CLI.

1. Create a marketplace

A marketplace exists before it has anywhere to publish to — creating and connecting are separate acts.

marketplaces { action: "create", name: "Team Plugins", slug: "team-plugins" }

2. Connect a GitHub repository

You need the Moxn GitHub App installed on the account or org that owns the repo. installations tells you what’s reachable:

marketplaces { action: "installations" }
marketplaces { action: "installations", installationId: 12345678 }   // + its repos

Then connect:

marketplaces {
  action: "connect",
  marketplaceId: "<uuid>",
  installationId: 12345678,
  owner: "acme",
  repo: "plugins"
}

Connecting indexes the repo — it reads and classifies the tree. It does not copy your content into Moxn, and it does not write to the repo.

An empty repository is fine, and is the normal starting point. Connect returns successfully with no baseline, and the next step fills it.

3. Scaffold, if the repo is empty

marketplaces { action: "scaffold", marketplaceId: "<uuid>" }

This publishes a starting tree: a marketplace manifest, one plugin, and one skill. It writes Claude-layout content only — the Codex and Cursor manifests are derived from it in the same commit, so never author those by hand.

It refuses a repo that already has plugins, and it refuses one whose .claude-plugin/marketplace.json cannot be parsed — a manifest we cannot read might list plugins, and scaffolding would overwrite it.

Scaffold commits immediately — there is no ref/branch parameter to target anything else, so it always writes straight to the connected repo’s default branch. Unlike edit (a draft) or commit to a feature branch, there is no review step here.

The example plugin’s directory defaults to example — pass pluginSlug to name it something else:

marketplaces { action: "scaffold", marketplaceId: "<uuid>", pluginSlug: "hello" }

In the web app this is the Add starter files button on a connected repo with nothing in it.

4. Read what’s there

marketplaces { action: "tree", marketplaceId: "<uuid>" }
marketplaces { action: "read_file", marketplaceId: "<uuid>", paths: ["plugins/hello/skills/greet/SKILL.md"] }

tree always reflects current GitHub state — there is no separate sync step.

read_file returns the latest text: live working state first (what someone has open and unsaved, plus any pending suggestions flattened to their accepted text), falling back to committed GitHub content.

5. Edit

Send the full new text of each file. The diff against the current text is computed for you.

marketplaces {
  action: "edit",
  marketplaceId: "<uuid>",
  ref: "my-feature-branch",
  writes: [{ path: "plugins/hello/skills/greet/SKILL.md", contents: "---\nname: greet\n---\n\n..." }]
}

A path the repo doesn’t have is a new file, not an error.

Each path comes back with a status:

Status	Meaning
suggested	Landed as reviewable tracked changes (markdown)
written	Landed directly in working state — code and config files have no suggestion overlay
unchanged	Your text matched what was already there
conflict	Someone edited the same block; re-read and resubmit — nothing was applied
error	Binary files, which have no text to edit

Read notes on every result — that is where anything that did not land is reported.

Nothing here reaches GitHub. Edits are drafts until you commit.

6. Commit — which is publishing

marketplaces {
  action: "commit",
  marketplaceId: "<uuid>",
  ref: "my-feature-branch",
  message: "Tighten the greet skill"
}

With no writes, commit publishes whatever is currently drafted — which is what you want after edit.

“Whatever is currently drafted” means every drafted file on that branch, not just the ones you touched. A draft left by an earlier session — yours or a colleague’s — is published too, under your commit message.

tree lists them in draftPaths. Check it before any commit that omits writes:

marketplaces { action: "tree", marketplaceId: "<uuid>", ref: "my-feature-branch" }
→ draftPaths: ["plugins/hello/skills/greet/SKILL.md", "plugins/hello/skills/translate/SKILL.md"]

If that list has more in it than you expect, pass explicit writes naming only the files you mean. Nothing else is published.

Every commit flattens pending suggestions to their accepted text and strips comment markers, so published files never contain review markup. The Codex and Cursor manifests are regenerated in the same commit.

Committing to the default branch is publishing to everyone who has the plugin installed. Use a branch when you want review first.

Working on a branch

marketplaces { action: "branches", marketplaceId: "<uuid>", branchOp: "create", newBranchName: "translations" }

Then pass ref: "translations" to edit and commit, and point the dev loop at it with --ref translations.

When it’s ready, open a pull request and merge it — both from Moxn:

marketplaces { action: "open_pr", marketplaceId: "<uuid>", branch: "translations", title: "Add translations" }
marketplaces { action: "pre_merge_report", marketplaceId: "<uuid>", branch: "translations" }
marketplaces { action: "merge_pr", marketplaceId: "<uuid>", branch: "translations", pullNumber: 12 }

pre_merge_report is advisory and gates nothing: unresolved comment threads, any review markup that reached committed bytes, stale vendor manifests, and whether Codex consumers will actually see the change. Review itself stays on GitHub — Moxn has no approvals or required checks.

ref and branch are the same parameter and are interchangeable on every action.

Comments stay in Moxn

Comments are margin notes on a draft. They are scoped to the branch they were written on, they do not travel to another branch, and they are never published — committing strips every marker from the bytes on every branch.

marketplaces { action: "comments", marketplaceId: "<uuid>", paths: ["…/SKILL.md"], commentOp: "list" }

Markdown files only. A thread goes orphaned when the text it was anchored to is edited away — it is kept and flagged, never dropped.

Component types

Type	Convention path
skill	skills/<name>/SKILL.md
command	commands/<name>.md
agent	agents/<name>.md
plugin manifest	<plugin>/.claude-plugin/plugin.json
marketplace manifest	.claude-plugin/marketplace.json

Author the Claude layout. The .codex-plugin/ and .cursor-plugin/ equivalents are generated on every publish — hand-editing them means the next commit overwrites your changes.

Once content is committed you can preview it locally with the dev loop, or see Publish & install for how consumers get it.