plugin-marketplace-setup

name: plugin-marketplace-setup description: Designs public or private Agent Skill and plugin marketplaces for Cursor, Claude Code, Codex, Zed, Open Plugin, and npx skills—manifest layout, install matrix, and Skill Steward vs product boundaries. Use when setting up a marketplace, distributing skills/plugins to a team, private registry, .cursor-plugin, .codex-plugin, .plugin, .claude-plugin, or skills.sh publishing. license: MIT type: governance metadata: author: skill-steward version: "1.0.0" category: marketplace

Plugin & skill marketplace setup

Ship skills (portable instructions), plugins (runtime wiring), and marketplaces (catalogs) without mixing them up.

Three layers (normative)

Rule: Instructions only → skill. Event hooks or multi-file wiring → plugin (references skills by id, do not fork SKILL.md).

Skill Steward meta-plugin means: a declarative manifest, referenced skill IDs, hook/rule snippets, and validated wiring artifacts. It does not mean a host marketplace submission has happened, and it must not silently mutate Cursor/Codex/Claude configuration. Host-specific install steps remain explicit in README/docs.

Public vs private (decision)

Skill Steward default: public arenukvern/skill_steward for meta-skills; hooks documented separately (npx skills does not install Cursor hooks).

Cross-agent install matrix (skills)

Use vercel-labs/skills as the shared installer:

npx skills add owner/repo                    # all skills, project scope
npx skills add owner/repo --skill my-skill   # one skill
npx skills add owner/repo -a cursor -a claude-code -a codex -a zed -y
npx skills add owner/repo -g                 # global (~/.agents/skills/)
npx skills add owner/repo --copy             # copy instead of symlink

Discovery also reads .claude-plugin/plugin.json and .claude-plugin/marketplace.json skill paths (Claude marketplace compatibility).

Hooks: supported on Claude Code, Cline, Kiro—not Cursor via npx skills. Cursor hooks need .cursor/hooks.json (Skill Steward example).

Cross-agent install matrix (plugins)

Reference product layout: product repository marketplace distribution configs.

Codex plugin notes

• Keep only plugin.json in .codex-plugin/; put skills/, .mcp.json, .app.json, hooks/, and assets/ at plugin root.
• Include skills, mcpServers, apps, or hooks in .codex-plugin/plugin.json only when the companion files/directories exist. Codex also checks default hooks/hooks.json.
• Marketplace files live at $REPO_ROOT/.agents/plugins/marketplace.json for repo/team catalogs or ~/.agents/plugins/marketplace.json for personal catalogs.
• Each marketplace entry must include policy.installation, policy.authentication, and category; keep source.path relative to the marketplace root and inside that root.
• Codex installs marketplace plugins into ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/; local source edits require reinstall/cache refresh before new threads see them.

Open Plugin portability

• Use .plugin/plugin.json when a plugin should be vendor-neutral across Open Plugin hosts.
• Add .codex-plugin/plugin.json, .cursor-plugin/plugin.json, or .claude-plugin/plugin.json only when the host needs a vendor-specific manifest.
• Do not confuse Skill Steward plugin.yaml with a host marketplace manifest. It is a local meta-plugin manifest for documenting Skill Steward wiring.

Scaffold a new marketplace repo

A. Skills-only marketplace (simplest — Skill Steward style)

my-skills/
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── skills.sh.json          # optional: skills.sh categories
├── README.md               # install commands
└── package.json            # optional: pnpm run validate

Publish: push public → npx skills add org/my-skills. No plugin manifest required. For customizing the repository page by defining groupings and categories in skills.sh.json, see the skills.sh customization docs.

B. Codex / Claude / Cursor marketplace (multi-plugin)

my-marketplace/
├── .agents/plugins/
│   └── marketplace.json    # Codex catalog
├── .claude-plugin/
│   └── marketplace.json    # Claude catalog, when needed
├── .cursor-plugin/
│   └── marketplace.json    # Cursor catalog, when needed
└── plugins/
    └── my-plugin/
        ├── .plugin/plugin.json
        ├── .codex-plugin/plugin.json
        ├── .claude-plugin/plugin.json
        ├── .cursor-plugin/plugin.json
        ├── skills/
        ├── hooks/
        └── .mcp.json

Codex entry: "source": {"source": "local", "path": "./plugins/my-plugin"} plus policy/category. Claude and Cursor keep their own marketplace shapes. Use only the vendor trees the target agents need.

C. Skill Steward meta-plugin (hooks + skill refs)

plugins/my-hook-pack/
├── plugin.yaml
├── README.md               # manual .cursor/hooks.json steps
├── hooks.json.snippet
└── hooks/

Canonical skills stay in skills/. See templates/plugin/.

Private marketplace checklist

1. Repo access — team can git clone (HTTPS token, SSH, or GHE app for Cursor team marketplaces).
2. Secrets — never commit tokens; document GITHUB_TOKEN / GITLAB_TOKEN for Claude auto-update on private marketplaces.
3. Install docs — one README block per channel (skills CLI vs Claude /plugin vs Cursor dashboard).
4. Versioning — bump version in plugin manifest per release; skills use git SHA via npx skills update.
5. CI — validate skills (pnpm run validate / dart run :steward validate in Skill Steward); product repos add contract tests.
6. Scope — project install (committed .agents/skills/) vs -g global; document team norm.

Skill Steward vs product repo

Do not put product MCP servers in Skill Steward. Cross-promote: npx skills add arenukvern/skill_steward --skill mcp-harness-repo-maintainer.

Workflow: add a distributable skill to Skill Steward

1. Follow skill-authoring-lifecycle — skills/{name}/SKILL.md.
2. Register in skills.sh.json + root README.md.
3. pnpm run validate in skill_steward.
4. After merge to main, public repo is installable via npx skills add arenukvern/skill_steward --skill {name}.
5. Optional: submit to skills.sh leaderboard (automatic for public repos with valid skills).

Workflow: add a Skill Steward plugin

1. Copy templates/plugin/ → plugins/{id}/.
2. List referenced skills in plugin.yaml (ids only).
3. Document install (Cursor hooks merge, etc.).
4. Update plugins/README.md.

Anti-patterns

• Putting hooks only in skills/ and expecting npx skills to wire Cursor
• Duplicating SKILL.md inside every plugin directory
• Private marketplace docs that only mention one agent
• Eternal plan files in marketplace repos (see plan hygiene)

Additional resources

• distribution-matrix.md — full channel table
• manifest-snippets.md — minimal JSON/YAML examples
• ADR 0004
• ADR 0006
• skills.sh customization docs

Install this skill

npx skills add arenukvern/skill_steward --skill plugin-marketplace-setup

Sources

See references/sources.md. When researching, follow skill-source-citations.