universal-plugin 0.11.1 → 0.11.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.11.1",
+	"version": "0.11.3",
 	"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"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.11.1",
+	"version": "0.11.3",
 	"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"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.11.1",
+	"version": "0.11.3",
 	"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"

package/dist/cli.mjs

@@ -6392,6 +6392,66 @@ const COPILOT_LSP_PATH = "lsp.json";
 /** Authored under the namespace, never derived: Copilot's canvas extensions have no canonical root
 *  location to derive from, so `--clean` must leave this subtree alone. */
 const COPILOT_AUTHORED_DIR = "extensions";
+/** The component paths each derived manifest accepts. A path on the shared extension reaches every
+*  derived manifest unless the vendor is listed here without it — then the build leaves it out and
+*  warns, as it does for `dependencies` (issue #132). A harness override is applied after this
+*  filter, so `harnesses.<vendor>` can still set any key on purpose.
+*  Each row is what the runtime reads: Claude Code's SchemaStore manifest schema, Cursor's published
+*  `plugin.schema.json`, and Codex's manifest loader, which reads `commands` too (migrated into
+*  skills on install). Codex's plugin-creator validator is narrower — it rejects `hooks` and
+*  `commands` — and is not what the row follows. With a root Agent Plugins `$schema`, Codex reads only
+*  `apps`, `hooks` and `interface` from its manifest and ignores the rest, so the Codex row is the
+*  superset its legacy (no-`$schema`) mode reads (`.research/plugin-schema/evidence.md` E28).
+*  Copilot CLI is absent: it reads the canonical manifest and derives no manifest of its own. */
+const VENDOR_COMPONENTS = {
+	"claude-code": /* @__PURE__ */ new Set([
+		"skills",
+		"commands",
+		"agents",
+		"hooks",
+		"mcpServers",
+		"lspServers",
+		"outputStyles",
+		"themes",
+		"channels",
+		"monitors"
+	]),
+	cursor: /* @__PURE__ */ new Set([
+		"skills",
+		"commands",
+		"agents",
+		"rules",
+		"hooks",
+		"mcpServers"
+	]),
+	codex: /* @__PURE__ */ new Set([
+		"skills",
+		"commands",
+		"apps",
+		"hooks",
+		"mcpServers"
+	])
+};
+/** Every component key some vendor reads. Only these are filtered; any other key on the extension is
+*  not a component and passes through as before. */
+const COMPONENT_KEYS = new Set(Object.values(VENDOR_COMPONENTS).flatMap((set) => [...set ?? []]));
+/** Splits the shared component config into what `vendor` reads and the component keys it has none
+*  of. A vendor without a table entry keeps everything. */
+function vendorComponentConfig(componentConfig, vendor) {
+	const supported = VENDOR_COMPONENTS[vendor];
+	if (!supported) return {
+		config: componentConfig,
+		dropped: []
+	};
+	const config = {};
+	const dropped = [];
+	for (const [key, value] of Object.entries(componentConfig)) if (COMPONENT_KEYS.has(key) && !supported.has(key)) dropped.push(key);
+	else config[key] = value;
+	return {
+		config,
+		dropped
+	};
+}
 /** What each vendor's build output occupies in the published package, for `plugin init --npm`'s
 *  `package.json` `files` wiring. */
 const VENDOR_SHIPPED_PATHS = {
@@ -6501,9 +6561,10 @@ function buildPlugin(root, opts = {}) {
 		const outputPath = path.join(root, relPath);
 		const outputDir = path.dirname(outputPath);
 		const vendorFields = harnesses[vendor] ?? {};
+		const components = vendorComponentConfig(componentConfig, vendor);
 		const vendorManifest = {
 			...metadata,
-			...componentConfig,
+			...components.config,
 			...vendorFields
 		};
 		const hooks = canonicalHooks ? translateHooks(canonicalHooks, vendor) : null;
@@ -6515,7 +6576,7 @@ function buildPlugin(root, opts = {}) {
 			if (mcp?.changed) warnings.push(`${vendor} reads the canonical plugin.json directly — the pinned mcpServers is not delivered to it`);
 			const overrides = Object.keys(vendorFields);
 			if (overrides.length > 0) warnings.push(`harnesses.${vendor} sets ${overrides.join(", ")}, but ${vendor} reads the canonical plugin.json directly — these fields are not delivered`);
-			writeSkillArtifacts(vendor, skills, opts, written, warnings);
+			writeSkillArtifacts(vendor, skills, opts, written);
 			const derived = deriveCopilotNamespace(root, componentConfig, hooks, indent, opts, written, warnings);
 			rows.push(derived ? {
 				vendor,
@@ -6528,6 +6589,7 @@ function buildPlugin(root, opts = {}) {
 			});
 			continue;
 		}
+		for (const key of components.dropped.filter((k) => !(k in vendorFields))) warnings.push(`${vendor} has no "${key}" component — the path is left out of ${relPath}`);
 		for (const drop of dedupeDrops(hooks?.drops ?? [])) warnings.push(`${vendor} cannot run the "${drop.type}" hook handler on ${drop.event} — dropped from the derived hooks file`);
 		const derivedHooksPath = path.join(outputDir, "hooks.json");
 		if (hooks?.changed) {
@@ -6555,7 +6617,7 @@ function buildPlugin(root, opts = {}) {
 				else if (!opts.dryRun && fs.existsSync(derivedHooksPath)) fs.unlinkSync(derivedHooksPath);
 			}
 			if (mcp?.changed && declaredMcp && !declaredMcp.inline) writeArtifact(derivedMcpPath, `${JSON.stringify({ mcpServers: mcp.servers }, null, indent)}\n`, opts, written);
-			writeSkillArtifacts(vendor, skills, opts, written, warnings);
+			writeSkillArtifacts(vendor, skills, opts, written);
 			rows.push({
 				vendor,
 				path: relPath,
@@ -6643,20 +6705,9 @@ function refreshCatalogs(root, manifest, vendors, opts, written, warnings) {
 		catalogRoot: repo.root
 	} : { catalogs: rows };
 }
-function writeSkillArtifacts(vendor, skills, opts, written, warnings) {
-	for (const skill of skills) {
-		if (vendor === "claude-code") {
-			writeClaudeSkill(skill, opts, written);
-			continue;
-		}
-		if (vendor === "cursor") continue;
-		if (skill.invocationPolicy === "model") continue;
-		if (vendor === "codex") try {
-			writeArtifact(path.join(os.homedir(), ".codex", "prompts", `${skill.name}.md`), skill.body, opts, written);
-		} catch (err) {
-			warnings.push(`Failed to write Codex prompt for skill "${skill.name}" (best-effort): ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
+function writeSkillArtifacts(vendor, skills, opts, written) {
+	if (vendor !== "claude-code") return;
+	for (const skill of skills) writeClaudeSkill(skill, opts, written);
 }
 /** Resolves a `pathValue` declaration — a single "./" path, an array of them, or a { paths: [...] }
 *  object — into the list of declared paths. Returns null when the field is absent or malformed, so
@@ -7664,7 +7715,7 @@ function initCommand$1(deps = { fs: realInitFs }) {
 	return cmd;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/@cyberuni+agent-harness@0.1.0/node_modules/@cyberuni/agent-harness/dist/index.js
+//#region ../../node_modules/.pnpm/@cyberuni+agent-harness@0.3.0/node_modules/@cyberuni/agent-harness/dist/index.js
 const harnessIds = [
 	"claude-code",
 	"cursor",
@@ -7675,7 +7726,10 @@ const harnessIds = [
 	"gemini-cli",
 	"qwen-code",
 	"vscode-copilot",
-	"cline"
+	"cline",
+	"crush",
+	"openhands",
+	"augment"
 ];
 function resolveHarnessEnvironment(environment = {}) {
 	return {
@@ -7896,6 +7950,50 @@ const storages = {
 				research: "E-CLINE-P3"
 			}]
 		};
+	},
+	crush: ({ env, homedir }) => {
+		return {
+			harness: "crush",
+			configDir: env.CRUSH_GLOBAL_CONFIG || join(env.XDG_CONFIG_HOME || join(homedir, ".config"), "crush"),
+			locations: []
+		};
+	},
+	openhands: ({ env, homedir }) => {
+		const configDir = env.OH_PERSISTENCE_DIR || env.OPENHANDS_PERSISTENCE_DIR || join(homedir, ".openhands");
+		const installed = join(configDir, "plugins", "installed");
+		return {
+			harness: "openhands",
+			configDir,
+			locations: [{
+				kind: "installed-plugins",
+				path: installed,
+				description: "Installed plugins, one folder each",
+				research: "E-OH-P3"
+			}, {
+				kind: "enabled-record",
+				path: join(installed, ".installed.json"),
+				description: "Install metadata keyed by plugin name, each with enabled: <bool>",
+				research: "E-OH-P4"
+			}]
+		};
+	},
+	augment: ({ homedir }) => {
+		const configDir = join(homedir, ".augment");
+		return {
+			harness: "augment",
+			configDir,
+			locations: [{
+				kind: "marketplaces",
+				path: join(configDir, "plugins", "marketplaces"),
+				description: "Marketplace checkouts",
+				research: "E-AUG-P2"
+			}, {
+				kind: "enabled-record",
+				path: join(configDir, "settings.json"),
+				description: "User settings; enabledPlugins maps plugin@marketplace to a boolean",
+				research: "E-AUG-P4"
+			}]
+		};
 	}
 };
 //#endregion
@@ -9459,13 +9557,25 @@ function syncVersion(root, syncFs) {
 //#region src/publish/cli.ts
 function publishCommand() {
 	const cmd = new Command("publish").description("Prepare plugin for publishing").helpCommand(false);
-	cmd.command("sync-version").description("Sync version from packagePath/package.json (default: the plugin root) into plugin.json").addOption(ROOT_OPTION).action((opts) => {
+	cmd.command("sync-version").description("Sync version from packagePath/package.json (default: the plugin root) into plugin.json").option("--no-build", "Skip re-deriving the vendor manifests").addOption(ROOT_OPTION).action((opts) => {
 		try {
-			const result = syncVersion(resolveRoot(opts.root), realSyncVersionFs);
-			output(result, {
+			const root = resolveRoot(opts.root);
+			const result = syncVersion(root, realSyncVersionFs);
+			const derived = [];
+			if (opts.build !== false) {
+				const build = buildPlugin(root, {});
+				for (const warning of build.warnings) process.stderr.write(`warn: ${warning}\n`);
+				for (const written of build.written) derived.push(path.relative(root, written).split(path.sep).join("/"));
+			}
+			output({
+				...result,
+				derived
+			}, {
 				version: result.version,
-				manifest: result.manifestPath
+				manifest: result.manifestPath,
+				derived
 			});
+			if (opts.build === false) process.stderr.write("→ universal-plugin plugin build\n");
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
 			process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -39,8 +39,8 @@
     "agents"
   ],
   "dependencies": {
-    "@cyberuni/agent-harness": "^0.1.0",
-    "@repobuddy/upx": "^0.1.0",
+    "@cyberuni/agent-harness": "^0.3.0",
+    "@repobuddy/upx": "^0.2.0",
     "@toon-format/toon": "^4.1.1",
     "commander": "^14.0.3",
     "semver": "^7.8.1"

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.11.1",
+	"version": "0.11.3",
 	"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"

package/readme.md

@@ -69,7 +69,7 @@ npx universal-plugin sync apply <action-id>
 ### publish
 
 ```sh
-npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json
+npx universal-plugin publish sync-version             # copy packagePath/package.json version into plugin.json, then rebuild
 ```
 
 This writes the canonical `plugin.json` only. Run `plugin build` afterwards, or the vendor manifests

package/references/slash-invocation.md

@@ -23,7 +23,7 @@ Deploy $ARGUMENTS.
 
 - 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.
+- Codex uses the skill itself. A user invokes it with `$skill` or `/skills`, so no command is derived. Codex custom prompts are deprecated and home-only, and `plugin build` never writes outside the plugin tree.
 - 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

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

@@ -73,15 +73,16 @@ Each `code` below is what the script emits.
 | `no-manifest` | no root `plugin.json` — this is not a plugin yet | `/universal-plugin:init-universal-plugin` |
 | `legacy-manifest` | root `plugin.json` with neither `$schema` nor `extensions` — a single-vendor manifest on the canonical path | `/universal-plugin:init-universal-plugin`, adopt route |
 | `vendor-only` | a vendor manifest with no canonical manifest above it | `/universal-plugin:init-universal-plugin`, adopt route |
-| `unbuilt` | a declared vendor whose output path holds no file — that runtime sees no plugin | `universal-plugin plugin build` |
-| `stale` | a derived manifest older than `plugin.json` | `universal-plugin plugin build` |
+| `unbuilt` | a declared vendor whose output path holds no file — that runtime sees no plugin | `/universal-plugin:build-plugin` |
+| `stale` | a derived manifest older than `plugin.json`; for a derived directory (`com.github.copilot/`), its newest file is what is compared | `/universal-plugin:build-plugin` |
 | `hand-edited` | a derived manifest that `build` would rewrite — the edit is already lost, it just has not been overwritten yet | move the field to the canonical manifest or to `harnesses.<vendor>`, then rebuild |
 | `unknown-vendor` | a `vendors` entry no build target matches; reported as `skipped` plus a warning | fix the id in `plugin.json` |
+| `unsupported-component` | a component path on the shared extension names a component one targeted vendor has none of (`agents` for Codex, `rules` for Claude Code, …); the build leaves it out of that vendor's manifest | declare the path under `harnesses.<vendor>` for the vendors that read it, or leave it — nothing is lost |
 | `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init-universal-plugin`, update route — move them to a vendor that has a derived manifest, or drop them |
 | `codex-fields-missing` | Codex is targeted without `version` or `description`; the build fails and writes **nothing at all**, including for the other vendors | add both to the canonical top level |
 | `version-drift` | the `packagePath` `package.json` and the canonical manifest carry different versions | `/universal-plugin:version` |
 | `unreleased-content` | shipped content was committed after the commit that set the current version — a consumer keyed on that version never re-extracts it | `/universal-plugin:version` |
-| `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `universal-plugin plugin build` |
+| `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `/universal-plugin:build-plugin` |
 | `stale-github-plugin` | a leftover `.github/plugin/plugin.json` from an older build — shadowed by root and no longer generated | `/universal-plugin:remove-plugin` |
 | `shadowing-manifest` | a `.plugin/plugin.json` exists — it outranks root in Copilot CLI's search order and silently shadows the canonical manifest | `/universal-plugin:remove-plugin` |
 | `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. On a repository still on the pre-0.6 layout the build stops rather than reporting an empty result, and the detail says so — read it beside `legacy-manifest` and `shadowing-manifest`, which name the signals | `/universal-plugin:init-universal-plugin`, adopt route on the pre-0.6 layout, else update route |
@@ -125,7 +126,7 @@ the diff:
 ```bash
 git status --short          # must be clean first, or the diff proves nothing
 npx universal-plugin plugin build
-git diff -- .claude-plugin .cursor-plugin .codex-plugin
+git diff -- .claude-plugin .cursor-plugin .codex-plugin com.github.copilot
 ```
 
 An empty diff means the derived manifests match what the canonical manifest says. Any hunk is drift —
@@ -179,6 +180,7 @@ is meant to ship — content that is still being worked on is not a finding to a
 | Task | Skill |
 |------|-------|
 | Create, adopt, or change what the plugin declares | `init-universal-plugin` |
+| Rebuild the derived manifests (`unbuilt`, `stale`, `copilot-root-components`) | `build-plugin` |
 | Move the plugin's version | `version` |
 | Remove derived manifests, or the plugin itself | `remove-plugin` |
 | Generate the repository's own marketplace catalogs | `marketplace` |

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

@@ -30,6 +30,15 @@ const readJson = (file) => {
 	}
 }
 const mtime = (file) => (fs.existsSync(file) ? fs.statSync(file).mtimeMs : null)
+// A derived directory (copilot-cli's com.github.copilot/) is as fresh as the newest file in it. The
+// directory's own mtime moves only when an entry is added, removed or renamed, so a rebuild that
+// rewrites its files in place leaves it as old as the first build (issue #144).
+const contentMtime = (abs) => {
+	const stat = fs.statSync(abs)
+	if (!stat.isDirectory()) return stat.mtimeMs
+	const files = fs.readdirSync(abs).map((entry) => contentMtime(path.join(abs, entry)))
+	return files.length === 0 ? stat.mtimeMs : Math.max(...files)
+}
 
 const VENDOR_MANIFESTS = ['.claude-plugin/plugin.json', '.cursor-plugin/plugin.json', '.codex-plugin/plugin.json']
 
@@ -207,7 +216,7 @@ if (build === null) {
 		const abs = path.join(root, row.path)
 		const exists = fs.existsSync(abs)
 		// `canonical` means the vendor reads root plugin.json; no derived file is expected.
-		const stale = row.status === 'built' && exists && manifestMtime !== null && mtime(abs) < manifestMtime
+		const stale = row.status === 'built' && exists && manifestMtime !== null && contentMtime(abs) < manifestMtime
 		vendors.push({ vendor: row.vendor, path: row.path, status: row.status, exists, stale })
 
 		if (row.status === 'built' && !exists) {
@@ -232,6 +241,13 @@ if (build === null) {
 				'no vendor is declared — the build writes nothing, so no runtime reads this plugin',
 				'/universal-plugin:init-universal-plugin, update route',
 			)
+		} else if (/has no "[^"]+" component/.test(warning)) {
+			add(
+				'unsupported-component',
+				'low',
+				warning,
+				'declare the path under harnesses.<vendor> for the vendors that read it, or leave it — the build already drops it',
+			)
 		} else if (/^Unknown vendor/.test(warning)) {
 			add('unknown-vendor', 'medium', warning, 'fix the vendor id in plugin.json')
 		} else {

package/skills/init-universal-plugin/references/vendors/claude-code.md

@@ -8,7 +8,8 @@ npx universal-plugin plugin build --vendor claude-code
 
 ## What lands in the derived manifest
 
-The shared metadata from the canonical top level, plus the component paths, plus whatever
+The shared metadata from the canonical top level, plus the component paths Claude Code reads (every
+one except `rules` and Codex's `apps`; the build drops those with a warning), plus whatever
 `extensions["org.cyberuni.universal-plugin"].harnesses["claude-code"]` sets. `$schema`, `extensions`,
 `vendors`, and `harnesses` are universal-plugin's own orchestration — they never
 appear in a vendor manifest.

package/skills/init-universal-plugin/references/vendors/codex.md

@@ -33,14 +33,35 @@ Codex's presentation metadata goes under its `harnesses` entry:
 }
 ```
 
-## Skills
+## Components
+
+What Codex reads from `.codex-plugin/plugin.json` depends on the root `plugin.json`:
+
+- **Root declares the canonical `$schema`** (`https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`,
+  the normal universal-plugin layout). Codex reads root `plugin.json` as an Agent Plugins manifest,
+  takes skills from `./skills` and MCP servers from `./mcp.json`, and uses `.codex-plugin/plugin.json`
+  only as an overlay for `apps`, `hooks`, and `interface`. Any other key there is ignored, and
+  commands are not read at all.
+- **Root has no `$schema`**. `.codex-plugin/plugin.json` is the manifest. Codex reads `skills`,
+  `commands`, `hooks`, `mcpServers`, and `apps` from it, and migrates each command into a skill on
+  install, falling back to `./commands/` when `commands` is absent.
 
-For every skill that is not `invocation-policy: model`, the build also writes
-`~/.codex/prompts/<name>.md` — the skill body, as a Codex prompt.
+Codex has no `agents`, `rules`, `lspServers`, `outputStyles`, `themes`, `channels`, or `monitors` in
+either case. `plugin build` leaves any of those out of `.codex-plugin/plugin.json` and warns
+(`codex has no "agents" component — the path is left out of .codex-plugin/plugin.json`); the other
+vendors still get the path. Set the path under `harnesses.codex` only if you mean Codex to see it
+anyway — a harness override is never filtered.
+
+The Codex runtime ignores keys it does not read. The plugin-creator validator Codex ships
+(`validate_plugin.py`) is stricter: it rejects any field outside its allowlist, including `commands`
+and `hooks`. That matters only if you submit the plugin through OpenAI's ingestion flow.
+
+## Skills
 
-Two things follow. It writes **outside the repository**, into the current machine's home directory,
-so it is not part of the plugin's tracked output and does not travel with a clone. And it is
-**best-effort**: a failure there becomes a build warning, not a failed build. Read the warnings.
+Codex reaches a plugin's skills natively. A user invokes one with `$name` or `/skills`, so the
+build derives nothing per skill for Codex. Codex custom prompts (`~/.codex/prompts/`) are deprecated
+and load only from the user's home directory, and the build never writes there. See
+[`codex-skill-invocation`](https://github.com/cyberuni/universal-plugin/blob/main/.research/codex-skill-invocation/conclusion.md).
 
 ## Hooks
 

package/skills/init-universal-plugin/references/vendors/cursor.md

@@ -22,6 +22,12 @@ Cursor's catalog metadata goes under its `harnesses` entry, not at the canonical
 }
 ```
 
+## Components
+
+Cursor reads `skills`, `commands`, `agents`, `rules`, `hooks`, and `mcpServers`. Its manifest schema
+is closed, so the build leaves `lspServers`, `outputStyles`, `apps`, and Claude Code's other
+components out of `.cursor-plugin/plugin.json` and warns.
+
 ## Skills
 
 Cursor reads `SKILL.md` straight from the path the manifest's `skills` field names, and lets the user

package/skills/version/README.md

@@ -18,7 +18,7 @@ The first question the skill asks is whether the repository uses changesets.
 
 - **With changesets** — the number is decided by the release, not by this skill. Add a changeset, let
   the release run, and `publish sync-version` carries the released number into the canonical
-  manifest.
+  manifest and re-derives the vendor manifests. With `--no-build`, `plugin build` is the next step.
 - **Without** — `plugin version <bump>` is the whole step. `scripts/version.mjs` runs it from the CLI
   shipped beside the skill, so nothing is downloaded.
 

package/skills/version/SKILL.md

@@ -22,12 +22,17 @@ test -d .changeset && echo "changesets"
 
 **If it does**, the version number is decided by changesets, not by you. Add a changeset and let the
 release run — the repo's `version` script should already call `publish sync-version`, which carries
-the released number from `package.json` into the canonical manifest:
+the released number from `package.json` into the canonical manifest and re-derives the vendor
+manifests, the same way `plugin version` does:
 
 ```bash
 npx universal-plugin publish sync-version
 ```
 
+If the script passes `--no-build`, it must run `plugin build` next (`/universal-plugin:build-plugin`);
+otherwise the vendor manifests and `com.github.copilot/` keep the old version, and a consumer's
+plugin cache never re-extracts.
+
 Do **not** run `plugin version` in a changesets repo — it would decide a number changesets is about
 to decide again.
 
@@ -109,6 +114,7 @@ Every guard resolves before the first write, so a failed run leaves the tree unt
 | Task | Skill |
 |------|-------|
 | Create, adopt, or change what the plugin declares | `init-universal-plugin` |
+| Re-derive the vendor manifests by hand | `build-plugin` |
 | Check whether the two authored versions agree | `doctor` |
 | Add a changeset for the change being released | `add-changeset` |
 | Refresh the repository's own marketplace catalogs after a bump | `marketplace` |