The Apache Magpie Marketplace

There is one Apache Magpie Marketplace, and it is the apache/magpie repository itself. You add it to your agent, and install plugins from it — one command per agent, all of them on the prerequisite page.

No third-party directory, no vendor “official” catalogue, and no account — the project publishes its own marketplace and you install straight from it.

From 0.2.0 it ships the manifests each major AI coding agent needs to read it, so the same one marketplace serves all of them; only the command to add it differs per agent. Installing from it is the recommended way to install Magpie. The pinned snapshot install is the fallback for the cases it does not cover.

Two manifest families: Agent Plugins 1.0 and client-specific

Magpie ships both of the manifest shapes an agent may look for, because as of 2026-08 no single one is read by every client.

Agent Plugins 1.0 (published 2026-08-06 by a TSC drawn from Amazon, Cursor, Microsoft, OpenAI, and Vercel; Google has since joined) is the vendor-neutral standard. A conformant plugin is a directory with a root plugin.json declaring the canonical $schema, plus skills in skills/<name>/SKILL.md and — optionally — MCP servers in a root mcp.json. Magpie’s skill tree already had exactly that layout, so conformance needed no file moves: the root plugin.json is the only addition.

Client-specific manifests stay alongside it, because the clients that predate the standard still read their own:

The manifests do not conflict: they sit at different paths, each client reads the one it documents, and every one of them points at the same single skills/ tree. tools/dev/check-family-plugins.py enforces that they all carry the same version and shared metadata, and that the AP1 manifest stays inside its closed ten-field schema — a Claude-only key such as skills or hooks copied into it is a fatal manifest error for an AP1 client, not an ignorable one.

Choosing a plugin: which families

The framework ships ten skill plugins, one per family, and you install as many as you want. There is no all-in-one plugin: installing everything was never the advice, because every installed skill costs context on every turn whether you use it or not.

Two further entries in the catalog are substrate plugins, which ship tooling rather than skills and are installed independently of the choice below: magpie-agent-guard (a PreToolUse hook that denies shell commands breaking a hard framework rule) and magpie-vetted-ops (a dispatcher for fixed, policy-scoped forge operations, so a session needs one allowlist entry instead of a dozen wildcard ask rules). Both run from the installed plugin, so no repository or worktree needs a local copy — and neither adds always-on skill context. Pick based on the trade-off between install simplicity and always-on token cost (each installed skill advertises a short description to the model on every turn — see “always-on” cost below).

Install only the families you use, and the always-on cost stays proportional to them: magpie-security ≈ 2.0k tokens, magpie-pairing ≈ 0.2k. Mixing is the normal case — e.g. magpie-release-management + magpie-security and nothing else. Adding a family later is one more install.

magpie-setup is the exception: it installs by default wherever a catalogue can say so, because it is the floor everything else is managed from.

Skills are invoked under the installing plugin’s namespace — e.g. /magpie-release-management:vote-tally.

A family plugin owns its skills as real directories under plugins/magpie-<family>/skills/. The flat skills/<skill> tree every path in this repository has always used is the mirror: each entry is a symlink pointing back into the plugin that owns it. Nothing is vendored and no skill exists twice — PRINCIPLES §13 holds.

Skill names differ by install method

The same skill is invoked by a different name depending on how you installed it. Each skill’s frontmatter name: is its plugin directory name (vote-tally, issue-triage, setup); the family plugin adds its namespace with a colon, while the portable /magpie-setup install puts a magpie- prefix on the directory it installs the skill under.

Why the difference:

• Marketplace install — the plugin name is the namespace, applied with a colon: /<plugin>:<name>. Claude Code and Codex take <name> from the frontmatter name:, VS Code from the directory; the two are the same by construction, so every harness shows /magpie-<family>:<alias>.
• Portable install (/magpie-setup snapshot) — the setup skill symlinks each framework skill under a magpie-<flat-name> directory (e.g. skills/release-vote-tally/ → magpie-release-vote-tally). Claude Code and VS Code name a repository skill after its directory, so it is invoked as a single hyphenated token, /magpie-<flat-name>; the prefix keeps framework skills from clashing with the adopter’s own. The listing shows shorter names than the command, though: Claude Code uses a repository skill’s frontmatter name: as its display label, so the / menu shows vote-tally beside /magpie-release-vote-tally — the same for a self-adopted framework checkout. Harnesses that name skills by frontmatter instead show the alias there: Codex as magpie-<family>:<alias> (it resolves the symlink back to the family plugin that owns the skill), Gemini CLI as the bare alias.
• Why the aliases. magpie-security + security-issue-triage would read /magpie-security:security-issue-triage, saying “security” twice. The family plugin owns each skill as a real directory named by the alias, and the flat skills/<name> tree mirrors it back with the family prefix kept. The rule lives in plugin_alias() in tools/dev/check-family-plugins.py, which also requires every alias to be unique across all families — Gemini CLI registers skills by name: in one flat namespace, which is why the pull-request family’s are pr-triage and pr-stale-sweep rather than a second triage and stale-sweep. check-doc-sync.py fails any doc that invokes a stuttering form, and the skill validator fails any name: that differs from its directory, as the Agent Skills specification requires.

Which form the docs use. Magpie’s user-facing docs — the quick start, the family READMEs, the top-level README — use the family-plugin form, because a marketplace install is the recommended path. The skills themselves refer to each other by bare skill name rather than any slash command, since a skill cannot know which way the reader installed it. If you are on the snapshot install, translate /<plugin>:<alias> to the single token /magpie-<directory-name> using the table above — note it is the directory name, not the alias.

Supported agents

Every agent below adds the same Apache Magpie Marketplace — the apache/magpie repository. What differs is only the command each one uses to add it and the manifest it reads. Pin to a released tag (e.g. 0.2.0) for reproducibility, or track main for the latest.

Quick reference:

Detailed steps per agent follow.

Claude Code

Commands: Prerequisite → Claude Code.

Adding the marketplace clones the repo and reads .claude-plugin/marketplace.json; installing a family reads that family’s plugin.json. Skills then arrive under the plugin namespace, e.g. /magpie-release-management:vote-tally.

Updating is /plugin marketplace update apache-magpie followed by /plugin update magpie-<family>@apache-magpie for each family you installed. On a version change the magpie-setup plugin’s bundled SessionStart hook also prompts you to run /magpie-setup upgrade.

Adding the marketplace from a tag rather than untagged pins which version the install tracks — see Versioning.

OpenAI Codex CLI

Commands: Prerequisite → OpenAI Codex CLI.

Adding the marketplace reads .agents/plugins/marketplace.json.

Which manifest Codex reads

Not .codex-plugin/plugin.json by default, which is what this page used to say. Codex resolves a manifest per plugin root, in this order:

1. The plugin root’s own plugin.json, taken when it is a regular file whose $schema sits under https://agent-plugins.org/schemas/.
2. Otherwise, the first of .codex-plugin/plugin.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json that exists.

When step 1 wins, .codex-plugin/plugin.json is not ignored — it is merged over the root manifest as an overlay, so it carries Codex-specific fields rather than the whole manifest.

For this repo that resolves two different ways:

The second row is why the ten family plugins install into Codex at all despite carrying only a Claude-Code manifest.

Verified against Codex’s source rather than its prose docs, which carry no plugins page: find_plugin_manifest_path in codex-rs/utils/plugins/src/plugin_namespace.rs, DISCOVERABLE_PLUGIN_MANIFEST_PATHS in codex-rs/exec-server-protocol/src/protocol.rs, and the overlay merge in codex-rs/core-plugins/src/manifest.rs. The plugin-authoring reference now ships inside the CLI as skill assets under codex-rs/skills/src/assets/samples/plugin-creator/references/.

All ten family plugins are offered here, and magpie-setup installs by default: a family plugin carries its skills as real directories, so Codex installs them intact (measured — magpie-security gives 15 of 15). The catalogue is checked against the live family: frontmatter by tools/dev/check-family-plugins.py, so it cannot drift into advertising a family that does not exist or omitting one that does.

Codex’s plugin/marketplace verbs are still evolving. If a command name differs, check codex plugin --help.

VS Code and GitHub Copilot

Agent Plugins 1.0 support is generally available in VS Code, Copilot CLI, the Copilot app, and the Copilot SDK on all Copilot plans. VS Code auto-detects the plugin format from the root manifest, and Magpie’s root plugin.json declares the AP1 $schema, so it is loaded as an AP1 package. Two ways in:

Commands: Prerequisite → VS Code / GitHub Copilot.

Two ways in, and they read different files: installing straight from the repo URL needs no marketplace at all, while adding apache/magpie as a plugin marketplace reads the root marketplace.json.

Either way the skills become available to the agent under the plugin that ships them. As with Codex, all ten families are offered.

Google Gemini CLI

Commands: Prerequisite → Google Gemini CLI.

The install reads gemini-extension.json and auto-discovers the skills under skills/. Invoke them by asking the agent in natural language or by skill name.

Gemini has no lifecycle hook, so the shipped GEMINI.md reminds you to run /magpie-setup upgrade when the version changes.

Cursor

Commands: Prerequisite → Cursor.

Cursor is one of the Agent Plugins 1.0 launch clients (and sits on the spec’s TSC), so it reads the root plugin.json.

Confirm the exact add flow in Cursor’s current docs — its self-serve marketplace surface is evolving.

microsoft/apm (multiplexer)

apm compiles one package to several agents at once (Claude, Cursor, Codex, Copilot, Gemini).

Commands: Prerequisite → microsoft/apm.

The install reads apm.yml (type: skill), deploys the skills into each supported agent’s directory, and writes an apm.lock.yaml — commit it to pin the exact resolved commit.

apm schema is v0.1 and may change; verify verbs with apm --help.

Kiro (AWS)

Kiro installs skills per-skill from a GitHub subdirectory (it does not consume the repo root). For each skill you want, point Kiro’s “install from GitHub” at that skill’s subdir on a pinned tag, e.g.:

https://github.com/apache/magpie/tree/0.2.0/skills/release-vote-tally

Kiro reads the skills/<name>/SKILL.md there.

OpenCode

OpenCode reads native Agent Skills from .opencode/skills/. Either:

• clone the skill directories you want into .opencode/skills/ (project) or ~/.opencode/skills/ (personal) from github.com/apache/magpie, or
• use a community installer (e.g. the opencode-skills-collection npm package) pointed at this repo.

JetBrains IDEs (IntelliJ IDEA, PyCharm, GoLand, …)

A JetBrains IDE is a host for an agent, not a distribution target of its own — which is why it appears in no table above and ships no manifest in this repo. Nothing here needs installing for IntelliJ; you install for the agent you run inside it.

With the Claude Code plugin for JetBrains, the install is the ordinary Claude Code one, run from the IDE’s Claude Code window — Prerequisite → JetBrains IDEs.

You do not have to run it twice. Claude Code keeps its plugin state in one user-scope store — ~/.claude/plugins/ (known_marketplaces.json and installed_plugins.json) — and every host that launches the same CLI reads it: the terminal, the VS Code extension, and the JetBrains plugin alike. Install from any one of them and the skills are there in the others. The same holds for the auto-install block: it lives in the project’s .claude/settings.json, so opening that project in IntelliJ picks it up exactly as opening it in a terminal does.

Project-scope installs are keyed by the project’s path, so a repo opened at the same path in the IDE and in a terminal shares them; a second clone elsewhere is a separate project and installs separately.

Not supported

• Windsurf — has no skills/rules marketplace; project rules are plain .windsurfrules files with no install mechanism. Skills would have to be converted by hand; there is no distribution channel.
• Goose (Block) — its extension registry is Model Context Protocol (MCP) servers, not SKILL.md skills. Distributing Magpie there would require wrapping skills behind an MCP server (a rebuild, not packaging).

Auto-install: arriving Magpie-ready

Everything above is a person typing an install command. A project can instead commit the wiring, so a contributor who clones it and opens their agent finds Magpie already there. Only Claude Code can actually do this, and the difference is structural rather than a gap someone forgot to fill.

What each harness supports

Codex’s INSTALLED_BY_DEFAULT is per-plugin, so it can express exactly the floor this page argues for: magpie-setup arrives installed, every other family stays AVAILABLE and opt-in. That only became possible once each family carried its own skills — while the all-in-one existed, defaulting it on meant defaulting everything on. check-family-plugins.py fails the build if either value drifts.

Claude Code: the default set

Add to the project’s .claude/settings.json — committed, so it applies to everyone who trusts the repo:

{
  "extraKnownMarketplaces": {
    "apache-magpie": {
      "source": { "source": "github", "repo": "apache/magpie" }
    }
  },
  "enabledPlugins": {
    "magpie-setup@apache-magpie": true,
    "magpie-utilities@apache-magpie": true,
    "magpie-agent-guard@apache-magpie": true
  }
}

Three plugins, for two different reasons.

setup and utilities are the framework’s two always-on families — the same pair the pinned-snapshot install wires unconditionally, with no way to ask for them or opt out. Between them a newcomer gets /magpie-setup to adopt and maintain the framework and /magpie-utilities:list-skills to discover everything else, at the smallest always-on cost. Every other family stays opt-in, which is the point.

magpie-agent-guard is not a family at all — it is a substrate plugin, a PreToolUse hook that denies shell commands which would break a hard framework rule (pinging maintainers, a Co-Authored-By trailer, marking a PR ready prematurely, leaking security language onto a public thread, emptying a PR via force-push). It is in the default set because a guard nobody remembered to install guards nothing: it costs no always-on context — it is a hook, not skills — and it is most valuable in exactly the sessions where nobody was thinking about it. It only ever denies, so the failure mode of having it on is a blocked command with a stated reason, not a silent action.

Pin the marketplace to a released tag by using "repo": "apache/magpie@0.2.0" if the project would rather not track main.

Contributors keep the last word: a plugin enabled this way still appears in /plugin, and anyone can disable it locally.

Automatic upgrade detection

When the marketplace updates the plugin to a new version, Magpie prompts you to run /magpie-setup upgrade — which reconciles the gitignored snapshot, the agentic overrides, and drift. This is detect-and-prompt, not auto-run: a plugin hook cannot invoke a slash command, and Magpie never mutates an adopter repo without the guided skill’s confirmation, so the trigger is automatic while the changes stay confirmed.

The hook writes its prompt to stdout, which is what a SessionStart hook exiting 0 has added to the session context — stderr on a zero exit reaches only the debug log. It is read-only apart from writing its own version marker, which goes to the client-provided persistent data directory (CLAUDE_PLUGIN_DATA / PLUGIN_DATA), falling back to $XDG_STATE_HOME/magpie — never inside the plugin checkout, which a plugin update may replace wholesale. It makes no network calls and touches nothing in the adopter repo.

Reconciliation when a skill first runs after an upgrade

marketplace update, plugin update and auto-update are all you need to get new skills onto your machine. They replace the plugin files and nothing else. They do not check whether your project’s configuration and overrides still match the new skills. Magpie does that itself, when you run a skill, so you have no extra step to remember.

Every skill runs a short self-check in its pre-flight. It compares the skill’s current configuration surface (its surface_hash) with the value recorded when this project was last reconciled. That value is kept in the reconciled: stamp: in the committed .apache-magpie.lock if the project is adopted, or in reconciled.json in your personal layer (<git-common-dir>/apache-magpie/) if you have only configured it (format in locks.md). Nothing is fetched over the network, and a skill whose surface has not changed stays silent.

After an upgrade, the first run of a changed skill is where reconciliation happens:

• The skill changed since the last reconciliation, for example a new requires_config entry or a moved anchor that one of your overrides points at. The skill shows the matching ⚠ and proposes the fix, then carries on with what you asked it to do. The warning is shown once per change and comes back only if the skill changes again.
• The project has never been reconciled (it has no stamp yet). The skill proposes a project-wide sweep instead. This proposal is shown once per installed version, not once per skill.

Nothing is changed without your confirmation. The check only detects and proposes. Applying a fix and writing the new stamp are left to setup, which asks you first.

To reconcile on demand, without waiting for a skill to notice, run:

/magpie-setup:setup reconcile

(/magpie-setup reconcile on a pinned-snapshot install.) This checks anchors and requires_config for every skill the project configures or overrides, proposes each fix separately, and writes a fresh stamp. It works with every install method. Add dry-run to see the report without changing anything. It is worth running right after a large upgrade, or before other contributors pick up the new version. Mechanics: reconcile.md.

The isolated setup is checked in the same pre-flight. If you use the secure agent setup on this machine, the first skill you run after an upgrade that changed its files (the sandbox wrapper and helper scripts, agent-guard, the container gateway, the dogfooded .claude/settings.json) proposes /magpie-setup:isolated-setup-update. The same suggestion also comes back weekly by default, and the interval can be changed. Run the skill directly at any time to check now. Details: Automatic reminders from the pre-flight.

Versioning

The plugin version tracks the framework version in pyproject.toml, which is the single authority every manifest mirrors verbatim — including the .devN suffix. Between releases the manifests therefore read 0.2.0.dev<YYYYMMDDHHMM>, not 0.2.0: a bare 0.2.0 would advertise a release that does not exist yet. Only a tagged release carries a bare version.

The dev suffix is a UTC timestamp, and it has to move for adopters to pick anything up. This marketplace is served straight from the main branch of a git repo, so consumers do install dev versions — the suffix reaching them is the normal case, not the exception. claude plugin update compares version strings, not commit SHAs: while the suffix stays frozen at a constant like .dev0, an adopter’s claude plugin update answers “already at the latest version” and never moves the pinned commit, however far behind main the installed copy has fallen. Their only recovery is claude plugin marketplace update followed by a full uninstall + reinstall of every plugin, which nobody discovers on their own.

The adopter’s half of this is auto-update, and it is off by default for apache-magpie because Claude Code disables it for third-party marketplaces. A stamp that moves reaches nobody whose client never refreshes the catalogue, so the install guide tells adopters to turn it on, and the same page covers the equivalent for Gemini (--auto-update), Codex (manual marketplace upgrade) and apm (lockfile by design).

When to bump. Not every PR — that would put every contributor in conflict with every other over one line, for no gain on changes nobody is waiting for. Bump when the work needs to reach installed copies: before pointing anyone at claude plugin update, before announcing a change adopters should take, or when a batch of merged work has piled up behind a stale stamp.

How to bump. From the Actions tab: bump dev version -> Run workflow. bump-dev-version.yml runs the three steps below, puts the result through the same checks a pull request gets, and opens it as a draft PR crediting whoever pressed the button. Review the diff, press Ready for review to start the required checks, then merge. workflow_dispatch is restricted by GitHub to accounts with write access, so the button is committers-only. See Running the dev loop for why it is a draft and what each job does.

It is manual on purpose: when a bump is wanted is the judgement above, not something a merge trigger can make. The same three steps still work by hand for a release or a local experiment — bump-dev-version.py, then check-family-plugins.py --fix and uv lock.

The stamp is minute-resolution and UTC, not local time: a repo with contributors in several timezones needs the string to sort in the order the bumps were actually made, and a date alone would collide whenever a day carries more than one.

Nothing is hand-edited. pyproject.toml feeds the four ecosystem manifests, and .claude-plugin/plugin.json — kept as the metadata anchor — in turn feeds the ten per-family manifests and the marketplace entries, which also inherit author, homepage, repository, and license. Bump project.version and run python3 tools/dev/check-family-plugins.py --fix; the same script runs as a prek hook in --fix mode, so a manifest left behind at the old version is regenerated in place and the run fails until the corrected file is staged. See release-management-config.md (version_manifest_files).

Verification status

Every manifest here has been checked against the vendor’s published documentation; what varies is whether it has also been exercised against a live install.

The skills themselves are checked against the Agent Skills specification, which AP1 defers to. Worth stating explicitly, because it looks like a problem and is not: 45 of the 74 description fields contain the framework’s <placeholder> syntax (<tracker>, <upstream>, …). The spec constrains description on length only — 1–1024 characters, non-empty — and places no restriction on angle brackets; the character-class rules apply to name, which every skill satisfies. So the placeholders are conformant, not a portability risk to design around.

Re-check each against the vendor’s current documentation before a marketplace publish. Manifests that fail live validation should be fixed here and re-released — none of them change how the ASF source release is built or signed.