> ## Documentation Index
> Fetch the complete documentation index at: https://moxn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## 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.

<Warning>
  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.
</Warning>

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`.

<Warning>
  "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.
</Warning>

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.

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

## 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](/guides/marketplaces/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.

<Note>
  `ref` and `branch` are the same parameter and are interchangeable on every action.
</Note>

## 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.

<Note>
  Once content is committed you can preview it locally with [the dev loop](/guides/marketplaces/dev-loop), or see [Publish & install](/guides/marketplaces/publishing) for how consumers get it.
</Note>