universal-plugin 0.2.1 → 0.3.0

package/dist/run.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+import * as fsNode from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import * as semver from "semver";
+//#region src/run/fs.ts
+function readInstall(dir) {
+	try {
+		const raw = fsNode.readFileSync(path.join(dir, "package.json"), "utf8");
+		const pkg = JSON.parse(raw);
+		if (typeof pkg.version !== "string") return void 0;
+		return {
+			dir,
+			version: pkg.version,
+			bin: pkg.bin
+		};
+	} catch {
+		return;
+	}
+}
+function packageDirIn(nodeModulesDir, pkg) {
+	return path.join(nodeModulesDir, ...pkg.split("/"));
+}
+/** Every ancestor `node_modules` directory from `startDir` up to the filesystem root, nearest
+*  first. */
+function ancestorNodeModulesDirs(startDir) {
+	const dirs = [];
+	let dir = startDir;
+	for (;;) {
+		dirs.push(path.join(dir, "node_modules"));
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return dirs;
+}
+/** Walks `node_modules` from `cwd` up through its ancestors, nearest first, collecting every
+*  install of `pkg` found along the way (an install missing a readable `package.json` version is
+*  skipped, not a match). */
+function findLocalInstalls(pkg, cwd) {
+	const installs = [];
+	for (const nodeModulesDir of ancestorNodeModulesDirs(cwd)) {
+		const install = readInstall(packageDirIn(nodeModulesDir, pkg));
+		if (install) installs.push(install);
+	}
+	return installs;
+}
+function globalRoot() {
+	try {
+		const out = spawnSync("npm", ["root", "-g"], { encoding: "utf8" }).stdout?.trim();
+		return out ? out : void 0;
+	} catch {
+		return;
+	}
+}
+function findGlobalInstall(pkg) {
+	const root = globalRoot();
+	if (!root) return void 0;
+	return readInstall(packageDirIn(root, pkg));
+}
+function spawnBin(binPath, args) {
+	const result = spawnSync(binPath, args, { stdio: "inherit" });
+	if (result.error) throw result.error;
+	return result.status ?? 1;
+}
+function spawnNpx(args) {
+	const result = spawnSync("npx", args, { stdio: "inherit" });
+	if (result.error) throw result.error;
+	return result.status ?? 1;
+}
+function realRunFs() {
+	return {
+		findLocalInstalls: (pkg) => findLocalInstalls(pkg, process.cwd()),
+		findGlobalInstall,
+		spawnBin,
+		spawnNpx
+	};
+}
+//#endregion
+//#region src/run/run.ts
+const NPM_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/** A loose approximation of npm's package-name rules: lowercase, alphanumeric/`.`/`_`/`-`, an
+*  optional `@scope/` prefix, non-empty. Good enough to reject the obviously malformed without
+*  chasing every edge npm itself enforces. */
+function isValidPackageName(name) {
+	if (!name || name.length > 214) return false;
+	return NPM_NAME_PATTERN.test(name);
+}
+/** Splits `<pkg>@<range>` on the **last** `@` at index > 0, so a scoped name's leading `@` survives.
+*  No `@` after index 0 — or a trailing `@` with an empty range — is a bare package (range `*`). A
+*  package name that is empty or violates npm's naming rules is a fail-loud error. */
+function parseSpec(spec) {
+	if (!spec) return {
+		ok: false,
+		error: "error: no package spec given"
+	};
+	const lastAt = spec.lastIndexOf("@");
+	let pkg;
+	let rangeRaw;
+	if (lastAt <= 0) {
+		pkg = spec;
+		rangeRaw = "";
+	} else {
+		pkg = spec.slice(0, lastAt);
+		rangeRaw = spec.slice(lastAt + 1);
+	}
+	if (!isValidPackageName(pkg)) return {
+		ok: false,
+		error: `error: unparseable package spec "${spec}"`
+	};
+	const bare = rangeRaw === "";
+	return {
+		ok: true,
+		spec: {
+			pkg,
+			range: bare ? "*" : rangeRaw,
+			bare
+		}
+	};
+}
+/** A valid semver range drives local-first matching; a non-empty non-semver spec (`next`,
+*  `latest`) is a dist-tag that can't be matched against an installed `package.json` version. */
+function isSemverRange(range) {
+	return semver.validRange(range) !== null;
+}
+/** Nearest-local → global, first install whose version satisfies `range`. `locals` must already be
+*  nearest-first. */
+function selectInstall(range, locals, globalInstall) {
+	for (const install of locals) if (semver.satisfies(install.version, range)) return install;
+	if (globalInstall && semver.satisfies(globalInstall.version, range)) return globalInstall;
+}
+/** Resolves the executable from a `package.json` `bin` field: a string bin, an object entry keyed
+*  by the package's unscoped name (even among several bins), or a single-entry object. A
+*  multi-entry object with no name match, or a missing `bin` field entirely, fails loud — `upx`
+*  never guesses which bin to run. */
+function resolveBinPath(pkgName, bin) {
+	if (bin === void 0) return {
+		ok: false,
+		error: `error: package "${pkgName}" declares no bin field`
+	};
+	if (typeof bin === "string") return {
+		ok: true,
+		bin
+	};
+	const entries = Object.entries(bin);
+	if (entries.length === 0) return {
+		ok: false,
+		error: `error: package "${pkgName}" declares no bin field`
+	};
+	if (entries.length === 1) return {
+		ok: true,
+		bin: entries[0][1]
+	};
+	const match = bin[pkgName.includes("/") ? pkgName.slice(pkgName.lastIndexOf("/") + 1) : pkgName] ?? bin[pkgName];
+	if (match) return {
+		ok: true,
+		bin: match
+	};
+	return {
+		ok: false,
+		error: `error: package "${pkgName}" declares multiple bins and none matches its name — upx never guesses which to run`
+	};
+}
+const KNOWN_LEADING_FLAGS = new Set(["--help", "-h"]);
+/** A flag is a token starting with `-`; `upx`'s own flags are recognized only before the first
+*  non-flag token (the package spec) — everything from the spec onward belongs to the child. An
+*  unknown flag before the spec fails loud. */
+function parseArgv(argv) {
+	if (argv.length === 0) return {
+		ok: false,
+		error: "error: no package spec given"
+	};
+	const first = argv[0];
+	if (first.startsWith("-")) {
+		if (KNOWN_LEADING_FLAGS.has(first)) return {
+			ok: true,
+			args: {
+				help: true,
+				spec: void 0,
+				childArgs: []
+			}
+		};
+		return {
+			ok: false,
+			error: `error: unknown flag "${first}"`
+		};
+	}
+	return {
+		ok: true,
+		args: {
+			help: false,
+			spec: first,
+			childArgs: argv.slice(1)
+		}
+	};
+}
+function fallbackNotice(pkg, range) {
+	return `upx: no installed ${pkg} satisfies "${range}", using npx`;
+}
+/** A dist-tag (`next`, `latest`) is not a version range, so the miss notice must not claim the
+*  installed versions failed to "satisfy" it — it never could. Keeps the fixed
+*  `upx: no installed <pkg>` prefix shared with {@link fallbackNotice}. */
+function distTagNotice(pkg, tag) {
+	return `upx: no installed ${pkg}; "${tag}" is a dist-tag, using npx`;
+}
+const HELP_TEXT = `Usage: upx <pkg>@<range> [args…]
+
+Runs a package's CLI from a local or global install matching <range>, falling
+back to npx when nothing installed satisfies it.
+
+Example:
+  $ upx cyberplace@^1.0.0 build
+`;
+/** Resolves `argv` (everything after `upx`) to a running child, per the Resolution algorithm in
+*  the spec: parse → classify the range → search local-then-global → resolve the bin → spawn, or
+*  fall back to npx with the spec exactly as given. */
+function runUpx(argv, fs) {
+	const parsedArgv = parseArgv(argv);
+	if (!parsedArgv.ok) return {
+		kind: "error",
+		message: parsedArgv.error
+	};
+	if (parsedArgv.args.help) return {
+		kind: "help",
+		text: HELP_TEXT
+	};
+	const specResult = parseSpec(parsedArgv.args.spec);
+	if (!specResult.ok) return {
+		kind: "error",
+		message: specResult.error
+	};
+	const { pkg, range, bare } = specResult.spec;
+	const childArgs = parsedArgv.args.childArgs;
+	const semverRange = isSemverRange(range);
+	if (semverRange) {
+		const install = selectInstall(range, fs.findLocalInstalls(pkg), fs.findGlobalInstall(pkg));
+		if (install) {
+			const binResult = resolveBinPath(pkg, install.bin);
+			if (!binResult.ok) return {
+				kind: "error",
+				message: binResult.error
+			};
+			const binPath = path.join(install.dir, binResult.bin);
+			return {
+				kind: "exit",
+				code: fs.spawnBin(binPath, childArgs)
+			};
+		}
+	}
+	const npxSpec = bare ? pkg : `${pkg}@${range}`;
+	return {
+		kind: "exit",
+		code: fs.spawnNpx([npxSpec, ...childArgs]),
+		notice: semverRange ? fallbackNotice(pkg, range) : distTagNotice(pkg, range)
+	};
+}
+//#endregion
+//#region src/run/cli.ts
+const outcome = runUpx(process.argv.slice(2), realRunFs());
+if (outcome.kind === "help") {
+	process.stdout.write(outcome.text);
+	process.exit(0);
+}
+if (outcome.kind === "error") {
+	process.stderr.write(`${outcome.message}\n`);
+	process.exit(1);
+}
+if (outcome.notice) process.stderr.write(`${outcome.notice}\n`);
+process.exit(outcome.code);
+//#endregion
+export {};

package/governances/plugin-design.md

@@ -4,16 +4,18 @@ Authoritative rules for creating, validating, and transforming cross-vendor agen
 
 A **plugin** is the distribution unit — it bundles skills, MCP servers, hooks, commands, agents, and other extensions into a single installable package. A **skill** is the capability unit inside a plugin. Install plugins; invoke skills.
 
-## Source of Truth: `.plugin/plugin.json`
+## Source of Truth: root `plugin.json`
 
-Author `.plugin/plugin.json` as the canonical manifest. All vendor manifests are derived from it via `build`. This file is never read directly by vendors at runtime; it is the single source that the build layer transforms into each vendor's manifest.
+Author `plugin.json` at the plugin root as the canonical manifest — the Agent Plugins Specification v1.0.0 shape (closed field set, `additionalProperties: false`). All vendor manifests are derived from it via `build`. This file is never read directly by vendors at runtime; it is the single source that the build layer transforms into each vendor's manifest.
 
-Schema declaration (first field):
+Schema declaration (first field, fixed by the spec):
 
 ```json
-{ "$schema": "https://schema.cyberuni.dev/universal-agent-plugin/v1.json" }
+{ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json" }
 ```
 
+Only ten top-level fields exist: `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, `extensions`. No other top-level keys are permitted. All `universal-plugin`-specific config — component paths, the vendor build-target list, and per-harness overrides — nests under `extensions["org.cyberuni.universal-plugin"]`.
+
 ### Required fields
 
 | Field | Type | Constraint |
@@ -34,12 +36,12 @@ Schema declaration (first field):
 
 ### Component path fields
 
-Each accepts `string | string[] | { paths: string[] }`. Every path must start with `./`. No `../` segments — traversal rejected by conformant hosts.
+All component paths and build config live under `extensions["org.cyberuni.universal-plugin"]` — the closed spec's field set has no top-level component keys. Each path field accepts `string | string[] | { paths: string[] }`. Every path must start with `./`. No `../` segments — traversal rejected by conformant hosts.
 
-| Field | Component | Core? | Notes |
+| Field (under `extensions["org.cyberuni.universal-plugin"]`) | Component | Core? | Notes |
 | --- | --- | --- | --- |
 | `skills` | Skill directories containing `SKILL.md` | Yes | Default: `./skills/` |
-| `mcpServers` | `.mcp.json` path or inline MCP config | Yes | Default: `./.mcp.json` |
+| `mcpServers` | `mcp.json` path or inline MCP config | Yes | Default: `./mcp.json` |
 | `commands` | Slash command `.md` files | Extended | Default: `./commands/` |
 | `agents` | Agent `.md` files | Extended | Default: `./agents/` |
 | `rules` | Context rule `.mdc` files | Extended | Cursor-only; ignored by other hosts |
@@ -49,16 +51,16 @@ Each accepts `string | string[] | { paths: string[] }`. Every path must start wi
 
 A conformant host must support at least one core component (`skills` or `mcpServers`). Extended types are silently ignored on non-supporting hosts — do not rely on them for core plugin functionality.
 
-### `vendorExtensions` field
+### `extensions["org.cyberuni.universal-plugin"]` — `vendors` and `harnesses`
 
-Declares which vendor manifests `build` generates, and provides vendor-specific fields for each. Each key is a recognized vendor ID; its presence drives build output. An empty `{}` opts into that vendor's output with no vendor-specific fields.
+`vendors` (array of vendor IDs) declares which vendor manifests `build` generates. `harnesses` (object keyed by vendor ID) provides vendor-specific fields for each declared vendor — the former `vendorExtensions.<vendor>` block, renamed and relocated. An empty `{}` entry in `harnesses` opts that vendor into build output with no vendor-specific fields, but the vendor ID must still be listed in `vendors` to be built.
 
 | Vendor ID | Output path | Required beyond `name` |
 | --- | --- | --- |
 | `claude-code` | `.claude-plugin/plugin.json` | none |
 | `cursor` | `.cursor-plugin/plugin.json` | none |
 | `codex` | `.codex-plugin/plugin.json` | `version`, `description` |
-| `copilot-cli` | `plugin.json` (repo root) | none |
+| `copilot-cli` | `plugin.json` (repo root) — the canonical manifest itself; nothing is derived | none |
 
 Vendor-specific extension fields:
 
@@ -82,8 +84,7 @@ Vendor-specific extension fields:
 
 ```
 <plugin-name>/
-├── .plugin/
-│   └── plugin.json               ← canonical source of truth
+├── plugin.json                    ← canonical source of truth
 │
 ├── skills/<skill-name>/SKILL.md  ← shared: all vendors, identical format
 │
@@ -112,12 +113,16 @@ Generated build artifacts (gitignore or commit — author's choice):
 ├── .codex-plugin/
 │   ├── plugin.json               ← generated
 │   └── hooks/hooks.json          ← generated (PascalCase, ${PLUGIN_ROOT} native)
-└── plugin.json                   ← generated (copilot-cli root manifest)
 ```
 
+`copilot-cli` has no entry here: it reads the canonical root `plugin.json` above, so nothing is
+generated for it. Copilot CLI checks `.plugin/plugin.json` → `plugin.json` →
+`.github/plugin/plugin.json` → `.claude-plugin/plugin.json` and takes the first match, so any file
+derived to one of the lower paths would be shadowed by root and never read.
+
 ## Vendor Manifest Derivation
 
-Build reads `.plugin/plugin.json`, applies the rules below, writes each vendor's output.
+Build reads root `plugin.json`, applies the rules below, writes each vendor's output.
 
 ### Metadata field mapping
 
@@ -210,7 +215,7 @@ If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattribut
 
 ## Component Authoring Rules
 
-**Skills:** Author `skills/<name>/SKILL.md` following the **skill-design** governance. Within a plugin, reference MCP tools by fully qualified name: `{plugin-name}:{server-name}__{tool-name}`.
+**Skills:** Author `skills/<name>/SKILL.md` following the **skill-design** governance. Within a plugin, reference MCP tools by fully qualified name: `{plugin-name}:{server-name}__{tool-name}`. Use the **slash-invocation** governance when a skill needs a user-only, model-only, or explicit both-invocation policy.
 
 **Commands:** One `.md` file per command in `commands/`. Filename (minus extension) is the command identifier. Optional frontmatter: `description`, `argument-hint`, `allowed-tools`, `disable-model-invocation`. `$ARGUMENTS` expands to user input.
 
@@ -241,7 +246,7 @@ If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattribut
 
 Default scope: **team**.
 
-**npm distribution:** All manifest directories (`.plugin/`, `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`) and component directories (`skills/`, `commands/`, `agents/`, `hooks/`) must be in `package.json#files`. `package.json` carries distribution metadata only — no plugin semantics.
+**npm distribution:** The canonical `plugin.json`, the generated manifest directories (`.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`), and component directories (`skills/`, `commands/`, `agents/`, `hooks/`) must be in `package.json#files`. `package.json` carries distribution metadata only — no plugin semantics.
 
 ## Anti-Patterns
 
@@ -276,4 +281,4 @@ npx universal-plugin@<version> governance show skill-repo-structure
 npx universal-plugin@<version> governance show agent-tool-output
 ```
 
-Spec: https://github.com/cyberuni/universal-plugin/blob/main/spec/universal-plugin-system.md
+Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md

package/governances/slash-invocation.md

@@ -0,0 +1,30 @@
+# Slash Invocation
+
+Use a skill's `invocation-policy` frontmatter field to say who may invoke it.
+`skills/` remains the only canonical prompt-artifact tree; do not create a
+parallel canonical `commands/` tree.
+
+```md
+---
+description: Deploy the application after running release checks.
+invocation-policy: user
+---
+
+Deploy $ARGUMENTS.
+```
+
+| Policy | Meaning | Default |
+| --- | --- | --- |
+| `user` | A person invokes the skill explicitly. Use for side-effecting workflows such as deploy or release. | No |
+| `model` | The model may invoke the skill, but it is hidden from the slash menu. Use for background knowledge. | No |
+| `both` | Either a person or the model may invoke the skill. | Yes |
+
+`plugin build` derives vendor behavior from that policy:
+
+- Claude Code uses the same `SKILL.md` and adds its native invocation flag.
+- Cursor receives a thin `.cursor/commands/<skill>.md` prompt insert for `user` and `both` skills.
+- Codex receives a best-effort, local-only `~/.codex/prompts/<skill>.md` for `user` and `both` skills. Codex has deprecated custom prompts, so the skill remains the primary integration.
+- Copilot CLI receives no derived command. Its `/skill-name` form is only a prompt hint, not deterministic invocation.
+
+If a workflow requires deterministic user-triggered invocation, document Copilot
+CLI as unsupported for that workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -11,14 +11,15 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cyberuni/cyberplace.git",
+    "url": "git+https://github.com/cyberuni/universal-plugin.git",
     "directory": "packages/universal-plugin"
   },
   "license": "MIT",
   "author": "unional <homawong@gmail.com>",
   "type": "module",
   "bin": {
-    "universal-plugin": "bin/universal-plugin.mjs"
+    "universal-plugin": "bin/universal-plugin.mjs",
+    "upx": "bin/upx.mjs"
   },
   "exports": {
     "./package.json": "./package.json"
@@ -26,13 +27,21 @@
   "files": [
     "bin",
     "dist",
-    "governances"
+    "governances",
+    "plugin.json",
+    ".claude-plugin",
+    ".cursor-plugin",
+    ".codex-plugin",
+    "skills",
+    "agents"
   ],
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "semver": "^7.8.1"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "@types/semver": "^7.7.1",
     "knip": "^6.14.1",
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",

package/plugin.json

@@ -0,0 +1,18 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "universal-plugin",
+	"version": "0.3.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"
+	},
+	"homepage": "https://github.com/cyberuni/universal-plugin",
+	"repository": "https://github.com/cyberuni/universal-plugin",
+	"license": "MIT",
+	"keywords": ["universal", "plugin", "agent", "cross-vendor"],
+	"extensions": {
+		"org.cyberuni.universal-plugin": {
+			"skills": "./skills/"
+		}
+	}
+}

package/readme.md

@@ -3,7 +3,13 @@
 [![npm version](https://img.shields.io/npm/v/universal-plugin.svg)](https://www.npmjs.com/package/universal-plugin)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Universal AI agent plugin build tool. Author one canonical plugin manifest (`.plugin/plugin.json`) and generate vendor-specific manifests for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
+Universal AI agent plugin build tool. Author one canonical plugin manifest (root `plugin.json`) and generate vendor-specific manifests for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
+
+## Specification
+
+This package follows the [Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec).
+Consult that repository's versioned specification and releases before changing manifest
+or component compatibility behavior; it is the canonical reference for the current standard.
 
 ## Usage
 
@@ -19,12 +25,28 @@ Or pin to an exact version for reproducible builds:
 npx universal-plugin@0.2.0 <command>
 ```
 
+## upx — the fast package runner
+
+`npm i -g universal-plugin` also puts a second bin, `upx`, on PATH. `upx <pkg>@^<major>` finds an
+already-installed version satisfying the range (local `node_modules` first, then global) and runs
+it directly — about 10× faster than `npx`'s ~1s per-call resolve+spawn cost — falling back to
+`npx` when nothing installed matches:
+
+```sh
+npm i -g universal-plugin
+upx cyber-skills@^2 audit validate
+```
+
+Use a caret range on the major, not an exact pin, so one global install serves every caller. `upx`
+needs to be installed to be on PATH; `npx` always ships with npm, so `npx` remains the safe default
+where `universal-plugin` isn't installed globally.
+
 ## Commands
 
 ### plugin — author the canonical manifest
 
 ```sh
-# Generate vendor manifests from .plugin/plugin.json
+# Generate vendor manifests from root plugin.json
 npx universal-plugin plugin build
 ```
 
@@ -45,10 +67,22 @@ npx universal-plugin sync apply <action-id>
 ### publish
 
 ```sh
-# Sync version from packagePath/package.json into .plugin/plugin.json
+# Sync version from packagePath/package.json into root plugin.json
 npx universal-plugin publish sync-version
 ```
 
+### marketplace
+
+```sh
+# Generate a local Codex catalog from canonical plugin manifests.
+npx universal-plugin marketplace init --codex --root .
+```
+
+Codex caches a local plugin install by its marketplace entry version. After changing packaged plugin
+files, update the canonical `plugin.json` version, regenerate the Codex catalog (use `--force` when
+replacing an existing catalog), reinstall the plugin, and start a new Codex session. This ensures the
+installed copy and its generated marketplace entry use the same version.
+
 ### governance
 
 Version-pinned agent-tool contracts, read at runtime.

package/skills/adopt-upx/README.md

@@ -0,0 +1,38 @@
+# adopt-upx skill
+
+Rewrites `npx <pkg>@<version>` references in `SKILL.md` files to a caret range on `upx`
+(`^<major>`, or `^0.<minor>` for a 0.x pin) — the fast local-first runner shipped by
+`universal-plugin`.
+
+## When to use
+
+When you want a project's skills to call CLIs via `upx` instead of `npx`, for the ~10× speed win
+on repeated invocations (local-first resolution vs. `npx`'s ~1s registry+spawn cost per call, even
+cached).
+
+## What it does
+
+1. Confirms `upx` is installed (`npm i -g universal-plugin`) and on PATH.
+2. Rewrites `npx <pkg>@<concrete-semver>` → `upx <pkg>@^<major>` (or `^0.<minor>` for a 0.x pin)
+   across a chosen scope:
+   - one specific skill (a path)
+   - a named set (a list of paths and/or globs)
+   - every skill in the project (`--all`)
+3. Leaves non-semver placeholders (`@<version>`), dist-tags (`@next`), already-`upx` references,
+   and any `pin-exempt: true` skill untouched.
+4. Reports a per-file rewrite count and a final tally. Safe to re-run (idempotent).
+
+## Mechanism
+
+`scripts/rewrite-upx.mjs` — a standalone Node script, no dependencies. See `SKILL.md` for usage.
+
+## Tradeoff
+
+A rewritten skill depends on `upx` being on PATH. `npx` ships with every npm install; `upx` only
+exists after `npm i -g universal-plugin`. This is an opt-in migration, not a safe default.
+
+## Install
+
+```bash
+npx skills add cyberuni/universal-plugin --skill adopt-upx
+```