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.

Workflow: repo-local copy/init pattern

Use this when a product repo needs agents to generate a local installer like flutter-mcp-toolkit init: a repo-owned script that copies canonical skills, host plugin manifests, MCP config, hooks, assets, and marketplace catalog files into Codex/Cursor/Claude layouts.

1. Inspect source truth — find canonical skills/, existing plugins/, .mcp.json/mcp.json, hooks, package/version metadata, assets, and current install docs. Do not generate host manifests from memory alone.
2. Choose the channel — use npx skills add --copy for skills-only distribution; use a repo-local copy/init script when skills must ship with MCP, hooks, commands, or assets; use host marketplace manifests only when the repo needs Codex/Cursor/Claude plugin install flows.
3. Create a product-owned plugin payload — keep canonical skills in the product repo, then copy or generate the install payload under plugin/ or plugins/{id}/ with .codex-plugin/, .cursor-plugin/, .claude-plugin/, optional .plugin/, skills/, hooks, MCP config, and assets.
4. Write explicit local scripts — generate an idempotent script owned by the product repo (tool/install_agent_bundle.dart, bin/<tool> init, or equivalent). The script should plan/copy directories, create host manifest directories, write marketplace root files, and report changed paths.
5. Document exact install commands — include separate Codex, Cursor, Claude, and skills-only commands. Name cache refresh/reinstall behavior and rollback steps.
6. Keep claims bounded — "local copy pattern implemented" does not mean public marketplace submission, host review, runtime MCP correctness, or fresh-agent proof.

See local-copy-pattern.md for a reusable layout, script skeleton, and validation checklist.

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
• Calling a repo-local copy/init script "public marketplace readiness" without host install proof
• Moving product-specific installer code into steward_cli before repeated repo evidence proves a generic Steward module is useful
• 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
• local-copy-pattern.md — repo-local copy/init script pattern
• 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.