universal-plugin 0.16.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -36,21 +36,22 @@
     ".codex-plugin",
     "com.github.copilot",
     "skills",
-    "agents"
+    "agents",
+    "CHANGELOG.md"
   ],
   "dependencies": {
     "@repobuddy/upx": "^0.2.0",
-    "@toon-format/toon": "^4.1.1",
-    "commander": "^15.0.0",
-    "cyber-agentkit": "^1.0.0",
-    "rolldown": "^1.2.11",
-    "semver": "^7.8.1"
+    "rolldown": "^1.2.11"
   },
   "devDependencies": {
+    "@toon-format/toon": "^4.1.1",
     "@types/node": "^24.10.1",
     "@types/semver": "^7.7.1",
     "ajv": "^8.20.0",
+    "commander": "^15.0.0",
+    "cyber-agentkit": "^2.0.0",
     "knip": "^6.14.1",
+    "semver": "^7.8.1",
     "tsdown": "^0.23.0",
     "tsx": "^4.22.3",
     "typescript": "^6.0.0",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.16.2",
+	"version": "0.17.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"
@@ -44,6 +44,10 @@
 					"source": "src/skill-scripts/run-cli.ts",
 					"command": "marketplace init"
 				},
+				"skills/marketplace/scripts/update.mjs": {
+					"source": "src/skill-scripts/run-cli.ts",
+					"command": "marketplace update"
+				},
 				"skills/marketplace/scripts/validate.mjs": {
 					"source": "src/skill-scripts/run-cli.ts",
 					"command": "marketplace validate"

package/readme.md

@@ -110,7 +110,7 @@ TOON by default; pass `--format json` for JSON.
 ### Reference documents
 
 This package ships its own documents (`plugin-design`, `slash-invocation`, `universal-plugin`) under
-`references/`. Read one with `npx cyber-agentkit reference show <name>` in any
+`references/`. Read one with `npx cyber-agentkit reference load <name>` in any
 project that depends on `universal-plugin`, or, from a skill, with the `reference` skill in the
 `cyber-agentkit` plugin.
 

package/skills/adopt-upx/scripts/rewrite-upx.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/rewrite-upx.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/adopt-upx/scripts/rewrite-upx.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/adopt-upx/scripts/rewrite-upx.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 //#region src/skill-scripts/rewrite-upx.ts

package/skills/build-plugin/SKILL.md

@@ -47,7 +47,7 @@ node scripts/build.mjs --root <plugin-root>
 
 Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI the project installed
 (`pnpm exec universal-plugin`), else the CLI pinned to the version this skill shipped with
-(`npx universal-plugin@0.16.2`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
+(`npx universal-plugin@0.17.0`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
 must name the directory that holds the canonical `plugin.json`.
 
 The command never prompts, so it is safe to run unattended.

package/skills/build-plugin/scripts/build.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/build-plugin/scripts/build.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/build-plugin/scripts/build.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/doctor-universal-plugin/SKILL.md

@@ -172,7 +172,7 @@ it does not, offer to add it — ask first, because both are the user's files:
   semantic-release bot opens.
 
 Use the locked `universal-plugin` from the repository's devDependencies when it has one; otherwise
-`npx universal-plugin@0.16.2`, pinned. This check matters most where the release tool picks the
+`npx universal-plugin@0.17.0`, pinned. This check matters most where the release tool picks the
 number, because nothing else runs between that bump and publish.
 
 ## Unreleased content

package/skills/doctor-universal-plugin/scripts/doctor.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/doctor.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/doctor-universal-plugin/scripts/doctor.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/doctor-universal-plugin/scripts/doctor.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";

package/skills/init-universal-plugin/references/create.md

@@ -43,7 +43,7 @@ node scripts/init.mjs --name <plugin-name> --vendor claude-code --vendor cursor
 ```
 
 Resolve `scripts/init.mjs` against this skill's directory; it runs the project's installed CLI, else
-the pinned `npx universal-plugin@0.16.2`. Add `--npm` when an npm package ships the plugin,
+the pinned `npx universal-plugin@0.17.0`. Add `--npm` when an npm package ships the plugin,
 which also wires that `package.json`'s `files` to carry the derived manifests, copies its `version`
 into the manifest, and, in a changesets repository, wires the root `version` script to run
 `plugin version --from-package` (SKILL.md Phase 3 asks before that rewrite).

package/skills/init-universal-plugin/scripts/init.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/init-universal-plugin/scripts/init.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/init-universal-plugin/scripts/init.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/README.md

@@ -3,7 +3,7 @@
 Run a repository's own plugin marketplace: generate the catalogs the runtimes read, list plugins
 that live elsewhere, and check that what is on disk is what each runtime will load.
 
-## A gateway over three routes
+## A gateway over four routes
 
 `SKILL.md` holds no procedure. It classifies the request and loads one reference:
 
@@ -11,7 +11,8 @@ that live elsewhere, and check that what is on disk is what each runtime will lo
 | --- | --- | --- |
 | `init` | The repository holds the plugins. Derive a catalog from `plugins/`, then offer the README install section. | `references/init.md` |
 | `add` | The plugin lives elsewhere — an npm package, a GitHub repo, or `<plugin>@<marketplace>`. | `references/add.md` |
-| `validate` | Check the catalogs against the schema each runtime loads. Both other routes end here. | `references/validate.md` |
+| `update` | An entry is already listed. Change its source, a pin, or one field, and keep the rest. | `references/update.md` |
+| `validate` | Check the catalogs against the schema each runtime loads. Every other route ends here. | `references/validate.md` |
 
 The split exists because the two writing routes answer different questions and share almost no
 steps. A single document had to hedge every instruction with "unless the plugin is not in this
@@ -22,6 +23,11 @@ discovery could never have produced them — and keeps a non-local source on a p
 discover, so a plugin shipped through npm is not rewritten to a repository path holding gitignored
 build output.
 
+`update` exists because the other writing routes cannot change one entry safely. `add --force`
+replaces the entry with what `add` derives and drops what it cannot, such as `category` and
+`author`, and the skill forbids patching a catalog by hand. `update` changes only the fields it is
+given and validates every catalog before it writes.
+
 ## Support is uneven, and the skill says so
 
 | Runtime | Reality |
@@ -62,5 +68,6 @@ document.
 - [Research: local marketplaces](https://github.com/cyberuni/universal-plugin/blob/main/.research/local-marketplaces/conclusion.md)
 - [`marketplace add` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/add/README.md)
 - [`marketplace init` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/init/README.md)
+- [`marketplace update` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/update/README.md)
 - [`marketplace validate` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/validate/README.md)
 - [Official Claude Code marketplace schema](https://json.schemastore.org/claude-code-marketplace.json)

package/skills/marketplace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: marketplace
-description: Use this skill to run a repository's own plugin marketplace — generate the catalogs Claude Code, Codex, GitHub Copilot CLI, and Cursor read, list a plugin that lives elsewhere (an npm package, a GitHub repo, or `<plugin>@<marketplace>`), check every catalog against the schema its runtime loads, and write the README install section. Trigger on "set up a local marketplace", "let users install this from my repo", "generate marketplace catalogs", "add a plugin to the marketplace", "list this npm package in my marketplace", "make this repo installable", "add install instructions to the README", or "check my marketplace catalogs".
-argument-hint: '[init|add|validate] [--claude] [--codex] [--copilot] [--cursor] [--dry-run] [--force]'
+description: Use this skill to run a repository's own plugin marketplace — generate the catalogs Claude Code, Codex, GitHub Copilot CLI, and Cursor read, list a plugin that lives elsewhere (an npm package, a GitHub repo, or `<plugin>@<marketplace>`), change one listed entry in place, check every catalog against the schema its runtime loads, and write the README install section. Trigger on "set up a local marketplace", "let users install this from my repo", "generate marketplace catalogs", "add a plugin to the marketplace", "list this npm package in my marketplace", "switch this entry to a url source", "bump the ref on this entry", "change the category of a marketplace entry", "make this repo installable", "add install instructions to the README", or "check my marketplace catalogs".
+argument-hint: '[init|add|update|validate] [--claude] [--codex] [--copilot] [--cursor] [--dry-run] [--force]'
 ---
 
 # marketplace
@@ -18,23 +18,26 @@ route names. Read only the one you need.
 | --- | --- | --- |
 | `init` | The repository **holds** the plugins. Derive a catalog from what is on disk, then offer the README install section. | `references/init.md` |
 | `add` | The plugin **lives elsewhere** — an npm package, a GitHub repository, or an entry another marketplace already publishes. | `references/add.md` |
+| `update` | An entry is **already listed** and needs a new source, a moved pin, or one field changed. Keeps every other field. | `references/update.md` |
 | `validate` | Check the catalogs the repository already carries against the schema each runtime loads. | `references/validate.md` |
 
 `init` and `add` are not alternatives. One repository can be both a plugin's home and a curated
 list, and the two commands compose: a regeneration keeps the entries `add` wrote, because discovery
 could never have produced them.
 
-Both routes end in `validate`. A catalog the runtime rejects is worse than no catalog — it is found,
+All three writing routes end in `validate`. A catalog the runtime rejects is worse than no catalog — it is found,
 read, and refused at install time, in someone else's terminal.
 
 ## Intake
 
 **Name the route and go.** "Set up a local marketplace", "make this repo installable", "generate the
-catalogs" → `init`. "Add repobuddy to the marketplace", "list this npm package" → `add`. "Check the
-catalogs" → `validate`. Load that reference and follow it; do not ask.
+catalogs" → `init`. "Add repobuddy to the marketplace", "list this npm package" → `add`. "Switch
+aced to a url source", "bump the ref", "change its category" → `update`. "Check the catalogs" →
+`validate`. Load that reference and follow it; do not ask.
 
 **Ask only when the invocation is bare.** One question: does the repository hold the plugins it is
-listing, or is it listing plugins that live somewhere else? Offer `init`, `add`, and `validate`.
+listing, or is it listing plugins that live somewhere else? Offer `init`, `add`, `update`, and
+`validate`.
 
 Discovery settles the question faster than the user can:
 
@@ -44,7 +47,7 @@ ls .claude-plugin/marketplace.json .agents/plugins/marketplace.json 2>/dev/null
 ```
 
 Plugins under `plugins/` and no catalog yet is `init`. A catalog already there and nothing new on
-disk is usually `add`.
+disk is usually `add`, or `update` when the user names an entry the catalog already lists.
 
 ## Where each runtime looks
 
@@ -69,7 +72,8 @@ their own catalog before the Claude one, which shields them. State per runtime w
   is worse than no install section, and that file is the only source of them. Widely-copied README
   snippets are not sources. The trap that lives there: Codex installs with `plugin add` where
   Copilot CLI uses `plugin install`.
-- **Never hand-author or hand-patch a catalog.** Generate it, then validate it. A catalog written by
+- **Never hand-author or hand-patch a catalog.** Generate it, then validate it. To change an entry
+  that is already listed, use `update`, not `add --force`, which drops the fields it cannot derive. A catalog written by
   copying fields out of `package.json` carries `owner` as a string and `repository` as an object,
   and Claude Code refuses it for either one.
 - **Name every catalog `marketplace.json`.** Codex discovers a catalog by that filename inside a
@@ -81,8 +85,8 @@ their own catalog before the Claude one, which shields them. State per runtime w
   have published will not understand why nobody can install.
 - **Ask before editing the README**, and before `--force` replaces anything a user may have written
   by hand.
-- Listing a plugin in the shared `cyberuni/cyberplace` repository is a different job: use
-  `publish-plugin`.
+- Listing a plugin in the shared `cyberuni/cyberplace` repository, or changing its entry there, is a
+  different job: use `publish-plugin`.
 
 ## Related skills
 
@@ -97,6 +101,7 @@ their own catalog before the Claude one, which shields them. State per runtime w
 
 - `references/init.md` — derive the catalogs from the plugins this repository holds
 - `references/add.md` — list a plugin that lives elsewhere
+- `references/update.md` — change one listed entry in place
 - `references/validate.md` — check the catalogs against the schema each runtime loads
 - `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)

package/skills/marketplace/references/add.md

@@ -107,7 +107,9 @@ fallback. Run `--dry-run` first and show the plan, including the skips. The comm
 | `skipped` | that runtime cannot resolve this source; the reason says which |
 
 An entry already listed **differently** stops the run and asks for `--force`. Read what would change
-before passing it: someone wrote that entry, and `--force` is what discards their version.
+before passing it: someone wrote that entry, and `--force` is what discards their version. To change
+a listed entry rather than replace it, use `update` (`references/update.md`), which keeps every field
+it is not asked about.
 
 The catalog is created if the repository has none, named and owned the same way `init` names it —
 from the root `plugin.json` author, with `--marketplace-name` and `--owner` to override. A

package/skills/marketplace/references/update.md

@@ -0,0 +1,75 @@
+# Route: update
+
+Change one entry the catalogs already list, and keep everything else about it. This is the route
+for an entry that is listed and wrong or stale: a new source, a moved pin, one field.
+
+`add --force` is not a substitute. It replaces the entry with what `add` can derive, so it needs
+`--owner` and the other `add` inputs again, and it drops what it cannot derive: `category`,
+`author`, any field a curator wrote by hand. Use `update` whenever the entry already exists.
+
+An entry that is not listed yet is `add`'s (`references/add.md`). A plugin this repository holds is
+re-derived by `init` or `plugin build`; reach for `update` there only for a field neither derives,
+such as `category`.
+
+## 1. Work out the change
+
+Name the entry by the name the catalogs list it under, then say what changes:
+
+| The user wants | Flags |
+| --- | --- |
+| Move the entry to another source, such as the `github` shorthand to an https `url` | `--source <spec>` |
+| Bump or change a pin | `--ref <branch-or-tag>`, `--sha <commit>` |
+| Change one field | `--description`, `--version`, `--homepage`, `--repository`, `--license`, `--keywords`, `--category` |
+| Remove a field or a pin | `--unset <field>`, repeatable; `--unset ref`, `--unset sha` |
+
+`--source` is read exactly the way `add` reads its spec, so the same collisions apply: write
+`./plugins/alpha` or pass `--path` for a directory, and `--npm`, `--github`, `--url`, and `--subdir`
+shape it the same way. A `<plugin>@<marketplace>` spec is refused; copying an entry is `add`'s job.
+
+Two pin rules to state to the user before running:
+
+- **A new git source keeps the old pin** unless `--ref` or `--sha` comes with it. Switching how a
+  repository is reached does not move which commit installs.
+- **`--ref` alone keeps an existing `sha`.** A sha pinned for the old ref then names a commit the
+  new one has moved past. When bumping a ref, pass `--unset sha` too, or pass the new `--sha`.
+
+## 2. Preview, then write
+
+```bash
+node scripts/update.mjs repobuddy --source https://github.com/cyberuni/repobuddy.git --dry-run
+```
+
+Resolve that path against this skill's own directory; `npx universal-plugin marketplace update` is
+the fallback. Run `--dry-run` first and show the plan. The command never prompts.
+
+| Status | Means |
+| --- | --- |
+| `updated` | the entry changed |
+| `unchanged` | already says exactly this |
+| `planned` | `--dry-run` only |
+| `skipped` | that catalog is missing, does not list the entry, or its runtime cannot install the new source; the reason says which |
+
+With no target flags all four catalogs are selected, so a `skipped` row for a catalog that never
+listed the entry is normal. Report every skip with its reason anyway. Two deserve a sentence each:
+
+- **A runtime that cannot install the new source keeps its old entry.** Moving an entry to `npm`
+  leaves Copilot CLI and Cursor on the source they had. Say so; the user may want those entries
+  removed, which is a hand decision this skill does not make.
+- **A shield catalog may appear.** Copilot CLI and Cursor read the Claude catalog when they have none
+  of their own. If the new source would break them there, their own catalog is written without the
+  entry, as `add` does. Tell the user the file appeared and why.
+
+The Codex catalog takes only `version` and `category` of the field flags, because that is all its
+entries carry. A description changed everywhere else is not missing from Codex by mistake.
+
+## 3. Validate
+
+The command checks every catalog it plans to write, with the same checks as `validate`, before it
+writes anything. An update that would introduce an issue stops and writes nothing; fix the input and
+rerun. An issue the catalogs already had does not stop it.
+
+So the write is safe, but the repository may still carry older issues. Follow
+`references/validate.md` and report its result, not just the update's.
+
+Then state plainly that nothing was published: the change sits in the repository until it is pushed
+and a user refreshes the marketplace.

package/skills/marketplace/references/validate.md

@@ -35,7 +35,7 @@ the fix is to run `init` or `add` so the runtime gets a catalog of its own.
 
 Fix an issue in the source it comes from, then regenerate. An entry's fields are derived, so an
 npm-style `repository` object belongs fixed in the plugin's `plugin.json` (for a discovered plugin)
-or passed as `--repository <url>` (for an added one).
+or set with `update <name> --repository <url>` (for an added one, `references/update.md`).
 
 The top-level `name` and `owner` live in the catalog itself, and `owner` must be an object —
 `{ "name": "…" }`, never the `"Name <email>"` string `package.json` uses.

package/skills/marketplace/scripts/add.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/install-docs.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/marketplace/scripts/install-docs.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/marketplace/scripts/install-docs.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";

package/skills/marketplace/scripts/marketplace.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/marketplace/scripts/marketplace.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/marketplace/scripts/marketplace.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/scripts/update.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/marketplace/scripts/update.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+import { spawnSync } from "node:child_process";
+//#region src/compile/scripts.ts
+/** The global the header assigns the script data to. Framework-neutral: a script's own code, or the
+*  library it inlines, reads it; universal-plugin depends on neither. */
+const SCRIPT_GLOBAL = "__SKILL_SCRIPT__";
+//#endregion
+//#region src/skill-scripts/cli-runner.ts
+/** The data `plugin build` embedded in this compiled script. */
+function skillScript() {
+	const data = globalThis[SCRIPT_GLOBAL];
+	if (data === void 0) throw new Error("this script runs only as compiled by `plugin build`");
+	return data;
+}
+/** Runs the universal-plugin CLI. A skill may be copied away from its package, so it never reaches
+*  for a CLI beside it: the project's installed CLI first, then the one pinned to this script's
+*  version, which `plugin version` stamps. */
+function runCli(args, options = {}) {
+	const { bin, package: pkg, version } = skillScript();
+	const name = bin ?? "universal-plugin";
+	if (spawnSync("pnpm", [
+		"exec",
+		name,
+		"--version"
+	], { encoding: "utf8" }).status === 0) return spawnSync("pnpm", [
+		"exec",
+		name,
+		...args
+	], {
+		encoding: "utf8",
+		...options
+	});
+	const pinned = `${pkg ?? "universal-plugin"}@${version ?? "latest"}`;
+	return spawnSync("npx", [pinned, ...args], {
+		encoding: "utf8",
+		...options
+	});
+}
+//#endregion
+//#region src/skill-scripts/run-cli.ts
+const script = skillScript();
+const command = Object.entries(script.commands).find(([, entry]) => entry === script.entry)?.[0];
+if (command === void 0) {
+	process.stderr.write(`${script.entry} declares no command in the scripts map\n`);
+	process.exit(1);
+}
+const result = runCli([...command.split(" "), ...process.argv.slice(2)], { stdio: "inherit" });
+process.exit(result.status ?? 1);
+//#endregion
+export {};

package/skills/marketplace/scripts/validate.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/marketplace/scripts/validate.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/marketplace/scripts/validate.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/publish-plugin/SKILL.md

@@ -239,6 +239,14 @@ The `source` field supports the same shapes as Claude Code (`url`, `github`, `gi
 
 If the plugin is already listed (this is an update), find its existing entry, update changed fields, and preserve any curator-added fields not in the standard shape. Do not overwrite `publishedAt` if present — add `"updatedAt": "<today>"` instead.
 
+For a change `marketplace update` covers (a new source, a moved `ref` or `sha` pin, or a field such as `description`, `version`, or `category`), run it in the marketplace checkout rather than editing the catalogs by hand. It keeps every field it is not given, curator fields included, and validates each catalog before writing:
+
+```bash
+npx universal-plugin marketplace update <plugin-name> --source <spec> --dry-run --root .
+```
+
+Drop `--dry-run` once the plan reads right. `updatedAt` and any other field it has no flag for are still set by hand.
+
 Show all prepared entries to the user and ask them to confirm before proceeding.
 
 ### 2f. Resolve the plugin's dependencies

package/skills/version/SKILL.md

@@ -74,7 +74,7 @@ node scripts/version.mjs --from-package
 ```
 
 Resolve that path against this skill's own directory; it runs the project's installed CLI
-(`pnpm exec universal-plugin`), else `npx universal-plugin@0.16.2` pinned to this skill's version.
+(`pnpm exec universal-plugin`), else `npx universal-plugin@0.17.0` pinned to this skill's version.
 `universal-plugin plugin version` on the `PATH` is the fallback. The command never prompts, so it is safe to run unattended once the
 source is decided.
 

package/skills/version/scripts/version.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.2","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.17.0","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace update":"skills/marketplace/scripts/update.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the