universal-plugin 0.4.0 → 0.5.0

package/skills/marketplace/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: marketplace
+description: Use this skill to let people install a plugin straight from its own repository — generate the local marketplace catalogs Claude Code, Codex, GitHub Copilot CLI, and Cursor read, and write the README install section that tells users what to type. Trigger on "set up a local marketplace", "let users install this from my repo", "generate marketplace catalogs", "add install instructions to the README", "how do people install this plugin", or "make this repo installable".
+argument-hint: '[--claude] [--codex] [--copilot] [--cursor] [--dry-run] [--force]'
+---
+
+# Local marketplace
+
+A repository can carry its own catalog, so a user adds the repository as a marketplace and installs
+from it. No service, no submission, no account.
+
+All four runtimes read such a catalog. Three of them let a user add it; Cursor's reaches users when
+an admin imports the repository as a team marketplace.
+
+| Runtime | Catalog it reads | What the user types |
+| --- | --- | --- |
+| Claude Code | `.claude-plugin/marketplace.json` | `/plugin marketplace add`, then `/plugin install` |
+| Codex | `.agents/plugins/marketplace.json`, or the Claude path | `codex plugin marketplace add`, then `codex plugin add` |
+| GitHub Copilot CLI | `.github/plugin/marketplace.json`, or the Claude path | `copilot plugin marketplace add`, then `copilot plugin install` |
+| Cursor | `.cursor-plugin/marketplace.json` | nothing; an admin imports the repository as a team marketplace |
+
+Read `references/runtimes.md` before writing any command into a README, and treat that file as the
+only source of install commands. The trap that lives there: Codex installs with `plugin add` where
+Copilot CLI uses `plugin install`.
+
+## Workflow
+
+### 1. Find what there is to list
+
+```bash
+ls plugins/*/plugin.json 2>/dev/null
+test -f plugin.json && cat plugin.json
+```
+
+`plugin init --vendor <id>` already registers the plugin it scaffolds in these catalogs, so a
+repository that has run it carries an entry before this skill starts. Read what is there first: this
+command regenerates a catalog from what it discovers, which is the whole repository rather than one
+plugin.
+
+A catalog lists plugins found at `<scan-root>/<plugin-dir>/plugin.json`, which defaults to
+`plugins/`. Pass `--plugin-scan-dir <dir>` when the repository keeps them elsewhere. A repository
+whose only plugin sits at its root has nothing to discover; say so rather than generating an empty
+catalog.
+
+Discovery reads a plugin's `name` and nothing else. A missing or malformed `name` stops the command
+before any write.
+
+### 2. Choose targets with the user
+
+Name the runtimes and what each one gets, using the table above. With no target flags the command
+selects all four.
+
+One catalog can serve two runtimes when the user wants fewer files: Codex reads the Claude catalog
+too, so `--claude` alone covers both. The reverse does not hold, because Claude Code rejects the
+Codex catalog for its missing `owner`. Generating both is the default, so each is idiomatic for its
+runtime.
+
+### 3. Generate
+
+```bash
+node scripts/marketplace.mjs --claude --copilot --dry-run
+```
+
+Resolve that path against this skill's own directory; `npx universal-plugin marketplace init` is the
+fallback. Run `--dry-run` first and show the plan. The command never prompts.
+
+Then generate for real. Selected targets compose as a union, so name every target you want each run.
+
+| Status | Means |
+| --- | --- |
+| `generated` | written |
+| `unchanged` | already correct, byte differences in key order and whitespace ignored |
+| `planned` | `--dry-run` only |
+| `empty` | nothing discovered for this target |
+
+A selected artifact that differs from what would be generated stops the whole run. That is the
+command protecting a hand-edited catalog. Read the difference, then re-run with `--force` only once
+you know what it discards.
+
+### 4. Offer the README section
+
+Ask before writing. A README is the user's document, and this is an edit to it, not a new file.
+
+```bash
+node scripts/install-docs.mjs
+```
+
+Stdout is one JSON object: `targets`, `repo`, and `markdown`. Insert `markdown` verbatim. It carries
+a section per generated catalog, built from the marketplace name and plugin names actually on disk.
+
+Check `repoResolved` first. When it is `false` the repository slug could not be found and the
+snippet contains `<owner>/<repo>`; ask the user for the slug and re-run with `--repo <owner>/<repo>`
+rather than leaving a placeholder in their README.
+
+If the README already has an install section, show the difference and let the user choose. Do not
+append a second one.
+
+### 5. Verify
+
+Re-run the generator and confirm every selected target reports `unchanged`. Confirm each catalog
+path exists. State plainly that nothing was published: these files sit in the repository until a
+user adds it as a marketplace.
+
+For Claude Code, check that each plugin `source` is a `./`-prefixed path that exists. Sources resolve
+against the directory containing `.claude-plugin/`, and they do not resolve at all for a user who
+adds the marketplace by direct URL to the JSON file.
+
+A local path is the cheapest end-to-end proof:
+
+```bash
+codex plugin marketplace add "$(pwd)"
+codex plugin list
+codex plugin marketplace remove <marketplace-name>
+```
+
+`codex plugin list` prints the manifest path it read, which is what tells you the catalog was found
+rather than merely present. Offer this check rather than running it unasked: it writes to the user's
+Codex config. Remove what you added.
+
+## Local development against Codex
+
+Codex installs a **copy** of the plugin at
+`~/.codex/plugins/cache/<marketplace>/<plugin>/<version>`, where the version is the one the plugin's
+own manifest carries. Editing the plugin's files does not reach that copy.
+
+After changing packaged files, install again and start a new session:
+
+```bash
+codex plugin add <plugin>@<marketplace>
+```
+
+That one command is the whole refresh: re-running it at the same version overwrites the cached copy
+with the current source, so neither `codex plugin remove` nor a version bump is needed. Codex reads
+the cache when a session starts, so the session you are in keeps the old copy — start a new one.
+
+The catalog entry's version is derived from the canonical manifest, so a version move updates both
+(`/universal-plugin:version` owns that). Codex itself does
+not read the entry's version; keeping it true is this project's policy, so the catalog never states
+a version the plugin does not have.
+
+## Rules
+
+- **Never publish a command that is not in `references/runtimes.md`.** An install command that fails
+  is worse than no install section. Widely-copied README snippets are not sources.
+- **Name every catalog `marketplace.json`.** Codex discovers a catalog by that filename inside a
+  supported directory. A file named anything else is invisible to it, whatever directory holds it.
+- **Do not write a Cursor install command.** Cursor has no command that adds a repository catalog;
+  a developer tests through `~/.cursor/plugins/local/<name>` and users get the plugin through a team
+  marketplace an admin imports.
+- **Ask before editing the README**, and before `--force` replaces a catalog the user may have
+  hand-edited.
+- This command publishes nothing and registers nothing. Say so in the report; a user who believes
+  they have published will not understand why nobody can install.
+- Listing a plugin in the shared `cyberuni/marketplace` repository is a different job: use
+  `publish-plugin`.
+
+## Related skills
+
+| Task | Skill |
+|------|-------|
+| Create or change the plugin being listed | `init` |
+| Check that the plugin's own manifests are current | `doctor` |
+| Move the version users will install | `version` |
+| Submit to the shared marketplace repository instead | `publish-plugin` |
+
+## References
+
+- `references/runtimes.md` — per-runtime install commands and their sources
+- [Research conclusion](https://github.com/cyberuni/universal-plugin/blob/main/.research/local-marketplaces/conclusion.md)
+- [`marketplace init` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/init/README.md)

package/skills/marketplace/references/runtimes.md

@@ -0,0 +1,104 @@
+# Install commands per runtime
+
+The only source of install commands for this skill. Every entry traces to vendor documentation
+reviewed on 2026-08-18 and recorded in `.research/local-marketplaces/evidence.md`. A command not
+listed here does not go into a README.
+
+## Claude Code — documented, complete
+
+Catalog: `.claude-plugin/marketplace.json` at the repository root (E-CC-M1).
+
+```
+/plugin marketplace add <owner>/<repo>
+/plugin install <plugin>@<marketplace-name>
+```
+
+`<marketplace-name>` is the `name` field inside `marketplace.json`, not the repository name (E-CC-M2).
+
+Both verbs also exist outside the session as `claude plugin marketplace add` and
+`claude plugin install`. In a non-interactive shell, `--yes` accepts the command string an install
+prints (E-CC-M3). Users refresh a catalog with `/plugin marketplace update`.
+
+Plugin `source` paths resolve against the marketplace root, the directory holding `.claude-plugin/`.
+They do not resolve when a user adds the marketplace by direct URL to the JSON file, so a repository
+distributing by URL must use a non-relative plugin source (E-CC-M4).
+
+Auto-update is off by default for third-party marketplaces, so a user who wants background refresh
+enables it once from `/plugin` → Marketplaces. That is a user-side setting; this skill does not
+change it.
+
+## GitHub Copilot CLI — documented, complete
+
+Catalog: `.github/plugin/marketplace.json`. Copilot CLI also accepts `marketplace.json` at the root,
+in `.plugin/`, or in `.claude-plugin/` (E-COPILOT-M3).
+
+```
+copilot plugin marketplace add <owner>/<repo>
+copilot plugin install <plugin>@<marketplace-name>
+```
+
+The marketplace's own `name` becomes its registration key, and a user cannot choose a local alias
+(E-COPILOT-M1). `copilot plugin install` also accepts `OWNER/REPO`, `OWNER/REPO:PATH`, a Git URL, or
+a local path, so a plugin is installable from a repository even without a catalog (E-COPILOT-M2).
+
+## Codex — works, and reads two paths
+
+Catalog: `.agents/plugins/marketplace.json`, which `marketplace init --codex` writes. Codex also
+reads `.claude-plugin/marketplace.json`, so a repository that generates only the Claude catalog is
+installable from Codex too (E-CODEX-M10, E-CODEX-M11).
+
+```
+codex plugin marketplace add <owner>/<repo>
+codex plugin add <plugin>@<marketplace-name>
+```
+
+`marketplace add` also accepts a local path, `owner/repo@ref`, an HTTPS Git URL, or an SSH Git URL,
+with `list`, `upgrade`, and `remove` beside it (E-CODEX-M3).
+
+**Codex installs with `plugin add`, not `plugin install`.** Copilot CLI is the opposite. Do not
+carry one runtime's verb over to the other.
+
+Neither verb appears in Codex's published documentation. Both are in the shipped CLI, verified on
+codex-cli 0.147.0.
+
+**Discovery is by filename.** Codex looks for `marketplace.json` inside a supported directory. These
+are read: `.claude-plugin/`, `.agents/plugins/`. These are not, with the correct filename in each:
+`.codex-plugin/`, `.plugin/`, `.github/plugin/`, the repository root (E-CODEX-M10).
+
+The two catalogs are not interchangeable in content. The Codex one carries `interface`, `policy`,
+`category`, and an object `source`; Codex accepts the Claude shape as well, but Claude Code rejects
+the Codex shape for its missing `owner` (E-CC-M5, E-CODEX-M9). Where a repository wants one file
+instead of two, that file is the Claude one.
+
+Codex copies an install to `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>`, keyed by the
+version the **plugin's own manifest** carries rather than the catalog entry's (E-CODEX-M13,
+E-CODEX-M15). A source edit is invisible until the plugin is installed again and a new session
+starts; `codex plugin add` on its own is the reinstall, because re-running it at the same version
+overwrites the cached copy (E-CODEX-M14). A catalog entry that declares no version installs normally
+(E-CODEX-M16).
+
+## Cursor — a catalog it reads, but no command to install from one
+
+Cursor reads a repository-local catalog: `.cursor-plugin/marketplace.json` or
+`.claude-plugin/marketplace.json` (E-CUR-M5), so the Claude catalog covers it. The documented shape
+is close to Claude Code's — `name`, an object `owner` carrying `name` and an optional `email`, and
+`plugins` whose `source` is a path inside the repository (E-CUR-M6). `marketplace init --cursor`
+writes it.
+
+Nothing on the command line consumes one. `cursor-agent` has no plugin subcommand (E-CUR-M2), and
+users install from the Customize sidebar, sourced from Cursor's reviewed marketplace,
+cursor.directory, or a team marketplace (E-CUR-M1). A repository catalog reaches users when an admin
+imports it: Dashboard → Plugins → Team Marketplaces → Add Marketplace → Import from Repo, after
+which Auto Refresh tracks the branch the marketplace is configured against (E-CUR-M7). So generate
+the file and write no Cursor install command.
+
+For local development, `universal-plugin plugin install` copies the plugin into
+`~/.cursor/plugins/local/<name>`; reload the window afterwards. It copies rather than symlinks
+because Cursor's scan resolves each symlink and rejects a target outside that directory (E-CUR-M4),
+which is what the `ln -sfn "$(pwd)"` recipe that used to sit here ran into.
+
+## When these decay
+
+A vendor command is a claim with a shelf life. Re-verify against the vendor page before relying on
+an entry that looks stale, and update the evidence file in the same change. The recheck triggers are
+listed in `.research/local-marketplaces/conclusion.md`.

package/skills/marketplace/scripts/install-docs.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Derives README install instructions from the marketplace catalogs a repository already carries.
+// Every command emitted here is traceable to vendor documentation; see
+// .research/local-marketplaces/evidence.md. Do not add a command without an evidence row.
+import { execFileSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+const argv = process.argv.slice(2)
+const rootFlag = argv.indexOf('--root')
+const root = path.resolve(rootFlag === -1 ? process.cwd() : (argv[rootFlag + 1] ?? process.cwd()))
+const slugFlag = argv.indexOf('--repo')
+
+const readJson = (file) => {
+	try {
+		return JSON.parse(fs.readFileSync(file, 'utf8'))
+	} catch {
+		return null
+	}
+}
+
+/** owner/repo, from the flag, the manifest's repository field, or the git remote. */
+function resolveSlug() {
+	if (slugFlag !== -1 && argv[slugFlag + 1]) return argv[slugFlag + 1]
+	const manifest = readJson(path.join(root, 'plugin.json'))
+	const repo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url
+	const fromManifest = repo?.match(/github\.com[/:]([^/]+\/[^/.]+)/)?.[1]
+	if (fromManifest) return fromManifest
+	try {
+		const remote = execFileSync('git', ['-C', root, 'remote', 'get-url', 'origin'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		return remote.match(/github\.com[/:]([^/]+\/[^/.\s]+)/)?.[1] ?? null
+	} catch {
+		return null
+	}
+}
+
+const slug = resolveSlug()
+const repoRef = slug ?? '<owner>/<repo>'
+
+const claude = readJson(path.join(root, '.claude-plugin/marketplace.json'))
+const copilot = readJson(path.join(root, '.github/plugin/marketplace.json'))
+// Codex reads its own catalog and the Claude one. Either makes a repository installable from Codex;
+// prefer its own when both exist. See references/runtimes.md (E-CODEX-M10).
+const codexOwn = readJson(path.join(root, '.agents/plugins/marketplace.json'))
+const codex = codexOwn ?? claude
+const cursor = readJson(path.join(root, '.cursor-plugin/marketplace.json'))
+
+const targets = []
+const sections = []
+
+const pluginNames = (catalog) => (catalog?.plugins ?? []).map((p) => p.name).filter(Boolean)
+
+if (claude) {
+	const names = pluginNames(claude)
+	const installs = (names.length > 0 ? names : ['<plugin>']).map((n) => `/plugin install ${n}@${claude.name}`)
+	targets.push('claude-code')
+	sections.push(['**Claude Code**', '', '```', `/plugin marketplace add ${repoRef}`, ...installs, '```'].join('\n'))
+}
+
+if (copilot) {
+	const names = pluginNames(copilot)
+	const installs = (names.length > 0 ? names : ['<plugin>']).map((n) => `copilot plugin install ${n}@${copilot.name}`)
+	targets.push('copilot-cli')
+	sections.push(
+		['**GitHub Copilot CLI**', '', '```', `copilot plugin marketplace add ${repoRef}`, ...installs, '```'].join('\n'),
+	)
+}
+
+if (codex) {
+	const names = pluginNames(codex)
+	// Codex installs with `plugin add`; Copilot CLI installs with `plugin install`. Not interchangeable.
+	const installs = (names.length > 0 ? names : ['<plugin>']).map((n) => `codex plugin add ${n}@${codex.name}`)
+	targets.push('codex')
+	sections.push(
+		[
+			'**Codex**',
+			'',
+			'```',
+			`codex plugin marketplace add ${repoRef}`,
+			...installs,
+			'```',
+			'',
+			'Start a new session before using the plugin.',
+		].join('\n'),
+	)
+}
+
+if (cursor) {
+	targets.push('cursor')
+	sections.push(
+		[
+			'**Cursor**',
+			'',
+			'This repository carries a Cursor catalog, but Cursor has no command that adds it from a',
+			'local path: a team admin imports the repository from the Cursor dashboard. To try the plugin',
+			'before then, run `npx universal-plugin plugin install --vendor cursor` in a clone, then',
+			'reload the window.',
+		].join('\n'),
+	)
+}
+
+const markdown = sections.length === 0 ? '' : ['## Install', '', sections.join('\n\n'), ''].join('\n')
+
+process.stdout.write(
+	`${JSON.stringify({
+		root,
+		repo: slug,
+		repoResolved: slug !== null,
+		targets,
+		markdown,
+	})}\n`,
+)

package/skills/marketplace/scripts/marketplace.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Runs `universal-plugin marketplace init` from the CLI that ships beside this skill, so catalog
+// generation never depends on a network fetch or on which version `npx` happens to resolve.
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// <package>/skills/<skill>/scripts/marketplace.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+
+process.argv.splice(2, 0, 'marketplace', 'init')
+await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))

package/skills/publish-plugin/SKILL.md

@@ -9,6 +9,10 @@ Guides adding an already-packaged plugin to a marketplace repo by opening a pull
 
 **Default marketplace repo:** `cyberuni/marketplace` (adjust if the user targets a different one)
 
+Listing a plugin in a shared repository is not the only way to distribute it. A repository can carry
+its own catalog and let users add it directly as a marketplace. That is the `marketplace` skill; the
+two compose, and neither replaces the other.
+
 ## Overview
 
 Publishing has three steps:
@@ -51,12 +55,10 @@ See `references/vendor-requirements.md` for required fields and hook casing rule
 
 ### 1c. Hook casing check
 
-If the plugin has hooks, verify each vendor manifest uses the correct event name casing:
-
-- Claude Code and Codex: **PascalCase** (`SessionStart`, `PreToolCall`)
-- Cursor and GitHub Copilot CLI: **camelCase** (`sessionStart`, `preToolCall`)
-
-Mixed casing causes silent hook failures at runtime.
+`plugin build` owns hook casing: the canonical file is authored in PascalCase, and Cursor's
+`.cursor-plugin/hooks.json` is derived from it. Verify the build ran rather than hand-checking the
+casing, and read its warnings — a handler type the vendor cannot run is dropped, so a hook can be
+absent from a vendor's file by design.
 
 ### 1d. Skills check (if present)
 
@@ -217,7 +219,7 @@ gh pr create \
 ## Checklist
 
 - [ ] All targeted vendor manifests present and valid
-- [ ] Hook event casing correct per vendor
+- [ ] `plugin build` ran, and its dropped-handler warnings were read
 - [ ] Semver version string
 - [ ] SPDX license identifier
 - [ ] Entry appended to each detected marketplace file
@@ -233,7 +235,7 @@ Return the PR URL to the user when done.
 
 | Problem | Fix |
 |---|---|
-| Hook events silently don't fire | Check casing: Claude Code/Codex need PascalCase, Cursor/Copilot CLI need camelCase |
+| Hook events silently don't fire | Re-run `plugin build`; check its warnings for a handler type that vendor cannot run |
 | Codex rejects manifest | `version` and `description` are required by Codex |
 | PR rejected: missing source link | Add `homepage` or `repository` to plugin.json |
 | Name conflict in marketplace | Check existing entries in each marketplace file first |

package/skills/publish-plugin/references/vendor-requirements.md

@@ -4,14 +4,14 @@
 
 **Manifest path:** `.claude-plugin/plugin.json`
 **Required fields:** `name`
-**Hook casing:** PascalCase (`SessionStart`, `PreToolCall`, `PostToolCall`, `Stop`)
+**Hook casing:** PascalCase (`SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`) — canonical form
 **Schema:** https://json.schemastore.org/claude-code-plugin-manifest.json
 
 ## Cursor
 
 **Manifest path:** `.cursor-plugin/plugin.json`
 **Required fields:** `name`
-**Hook casing:** camelCase (`sessionStart`, `preToolCall`, `postToolCall`)
+**Hook casing:** camelCase (`sessionStart`, `preToolUse`, `postToolUse`) — derived by `plugin build`
 **Schema:** https://raw.githubusercontent.com/cursor/plugins/main/schemas/plugin.schema.json
 
 ## Codex
@@ -24,15 +24,18 @@
 
 **Manifest path:** `plugin.json` (root of plugin directory)
 **Required fields:** `name`
-**Hook casing:** camelCase (follows Cursor convention)
+**Hook casing:** either — PascalCase selects its Claude-compatible payload format, so the canonical file serves it
 **Notes:** Also searches `.plugin/plugin.json` as a fallback path
 
 ## Hook event name reference
 
-| Canonical | Claude Code / Codex | Cursor / Copilot CLI |
-|---|---|---|
-| session start | `SessionStart` | `sessionStart` |
-| session end | `SessionStop` | `sessionStop` |
-| before tool | `PreToolCall` | `preToolCall` |
-| after tool | `PostToolCall` | `postToolCall` |
-| agent stop | `Stop` | `stop` |
+Author the canonical name; `plugin build` derives Cursor's. Claude Code, Codex, and Copilot CLI read
+the canonical name as authored.
+
+| Canonical (Claude Code, Codex, Copilot CLI) | Cursor |
+|---|---|
+| `SessionStart` | `sessionStart` |
+| `SessionEnd` | `sessionEnd` |
+| `PreToolUse` | `preToolUse` |
+| `PostToolUse` | `postToolUse` |
+| `Stop` | `stop` |

package/skills/version/SKILL.md

@@ -111,7 +111,8 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 | Create, adopt, or change what the plugin declares | `init` |
 | Check whether the two authored versions agree | `doctor` |
 | Add a changeset for the change being released | `add-changeset` |
-| List the released plugin in a marketplace | `publish-plugin` |
+| Refresh the repository's own marketplace catalogs after a bump | `marketplace` |
+| List the released plugin in the shared marketplace | `publish-plugin` |
 
 ## References