Plugin Marketplace Setup

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.