universal-plugin 0.16.3 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.16.3",
+  "version": "0.17.1",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -41,17 +41,17 @@
   ],
   "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.3",
+	"version": "0.17.1",
 	"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

@@ -74,7 +74,7 @@ npx universal-plugin publish check-version            # fail when any place carr
 ```
 
 `publish sync-version` and `plugin bundle` are deprecated aliases of `plugin version --from-package`
-and `plugin version`. They print a warning and are removed in the next minor release.
+and `plugin version`. They print a warning and will be removed in a later release.
 
 ### marketplace
 
@@ -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/references/plugin-design.md

@@ -1,12 +1,12 @@
 # Plugin Design
 
-Authoritative rules for creating, validating, and transforming cross-vendor agent plugins. Apply when creating, auditing, or distributing a plugin; see **skill-design** governance for standalone skill authoring rules.
+Authoritative rules for creating, validating, and transforming cross-vendor agent plugins. Apply when creating, auditing, or distributing a plugin; see the **skill-design** reference for standalone skill authoring rules.
 
 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: root `plugin.json`
 
-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.
+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`. GitHub Copilot CLI reads this file directly at runtime; every other vendor reads the manifest the build layer derives from it.
 
 Schema declaration (first field, fixed by the spec):
 
@@ -98,8 +98,7 @@ Vendor-specific extension fields:
 │
 ├── hooks/hooks.json              ← canonical hooks (PascalCase, ${PLUGIN_ROOT})
 │
-├── .mcp.json                     ← source of truth (all vendors)
-├── mcp.json -> .mcp.json         ← symlink (Cursor + open-plugin-spec)
+├── mcp.json                      ← MCP config (fixed location, all vendors)
 │
 └── README.md
 ```
@@ -141,11 +140,11 @@ Build reads root `plugin.json`, applies the rules below, writes each vendor's ou
 | Canonical field | Claude Code | Cursor | Codex | Copilot CLI |
 | --- | --- | --- | --- | --- |
 | `skills` | ✓ | ✓ | ✓ | ✓ |
-| `mcpServers` | ✓ → `./.mcp.json` | adapt → `./mcp.json` (symlink) | ✓ → `./.mcp.json` | ✓ |
+| `mcpServers` | ✓ → `./mcp.json` | ✓ → `./mcp.json` | ✓ → `./mcp.json` | ✓ |
 | `commands` | ✓ | ✓ | **omit** | ✓ |
 | `agents` | ✓ | ✓ | **omit** | ✓ |
 | `rules` | **omit** | ✓ | **omit** | **omit** |
-| `hooks` | adapt → PascalCase, `${CLAUDE_PLUGIN_ROOT}` | adapt → camelCase, pass-through env | ✓ → PascalCase, `${PLUGIN_ROOT}` native | adapt → camelCase, pass-through env |
+| `hooks` | adapt → PascalCase, `${CLAUDE_PLUGIN_ROOT}` | adapt → camelCase, pass-through env | ✓ → PascalCase, `${PLUGIN_ROOT}` native | ✓ → PascalCase (selects the Claude-compatible payload) |
 | `lspServers` | ✓ | **omit** | **omit** | **omit** |
 | `outputStyles` | ✓ | **omit** | **omit** | **omit** |
 | `dependencies` | ✓ | **drop + warn** | **drop + warn** | **drop + warn** |
@@ -193,15 +192,15 @@ Canonical hooks file uses **PascalCase** event names. Build translates per vendo
 
 | Canonical (PascalCase) | Claude Code | Cursor | Codex | Copilot CLI |
 | --- | --- | --- | --- | --- |
-| `PreToolUse` | `PreToolUse` | `preToolUse` | `PreToolUse` | `preToolUse` |
-| `PostToolUse` | `PostToolUse` | `postToolUse` | `PostToolUse` | `postToolUse` |
+| `PreToolUse` | `PreToolUse` | `preToolUse` | `PreToolUse` | `PreToolUse` |
+| `PostToolUse` | `PostToolUse` | `postToolUse` | `PostToolUse` | `PostToolUse` |
 | `PostToolUseFailure` | `PostToolUseFailure` | — (drop+warn) | — (drop+warn) | — (drop+warn) |
-| `SessionStart` | `SessionStart` | `sessionStart` | `SessionStart` | `sessionStart` |
-| `SessionEnd` | `SessionEnd` | `sessionEnd` | `SessionEnd` | `sessionEnd` |
-| `Stop` | `Stop` | — (drop+warn) | — (drop+warn) | `agentStop` |
+| `SessionStart` | `SessionStart` | `sessionStart` | `SessionStart` | `SessionStart` |
+| `SessionEnd` | `SessionEnd` | `sessionEnd` | `SessionEnd` | `SessionEnd` |
+| `Stop` | `Stop` | — (drop+warn) | — (drop+warn) | `Stop` |
 | `UserPromptSubmit` | `UserPromptSubmit` | `beforeSubmitPrompt` | — (drop+warn) | — (drop+warn) |
-| `Notification` | `Notification` | — (drop+warn) | — (drop+warn) | `notification` |
-| `PermissionRequest` | `PermissionRequest` | — (drop+warn) | — (drop+warn) | `permissionRequest` |
+| `Notification` | `Notification` | — (drop+warn) | — (drop+warn) | `Notification` |
+| `PermissionRequest` | `PermissionRequest` | — (drop+warn) | — (drop+warn) | `PermissionRequest` |
 | `SubagentStart` | — | `subagentStart` | — | — |
 | `SubagentStop` | — | `subagentStop` | — | — |
 | `PreCompact` | `PreCompact` | `preCompact` | — | — |
@@ -230,20 +229,9 @@ Events not in this table: pass through for `claude-code`; drop + warn for all ot
 
 Build generates vendor-specific versions. Do not hand-author the generated hook files.
 
-## MCP: Symlink Rule
+## MCP: `mcp.json`
 
-`.mcp.json` is the source of truth. `mcp.json` is always a symlink — never a regular file.
-
-```bash
-ln -sf .mcp.json mcp.json
-```
-
-| Runtime | Reads |
-| --- | --- |
-| Claude Code, Codex | `.mcp.json` |
-| Cursor, open-plugin-spec | `mcp.json` (via symlink) |
-
-If the repo needs explicit symlink tracking: `mcp.json symlink` in `.gitattributes`. MCP server startup failures are non-fatal.
+`mcp.json` at the plugin root is the Agent Plugins Specification's fixed MCP location, Author it as a regular file. `build` points each derived manifest at it, unless it has to change an entry for that vendor; then it writes the changed copy beside the vendor manifest. MCP server startup failures are non-fatal.
 
 ### Pinning a self-published server to the plugin version
 
@@ -271,9 +259,9 @@ A plugin whose MCP server is its own npm package writes an unpinned invocation
 
 ## 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}`. Use the **slash-invocation** governance when a skill needs a user-only, model-only, or explicit both-invocation policy.
+**Skills:** Author `skills/<name>/SKILL.md` following the **skill-design** reference. Within a plugin, reference MCP tools by fully qualified name: `{plugin-name}:{server-name}__{tool-name}`. Use the **slash-invocation** reference 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.
+**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 on Claude Code and stays literal on other runtimes.
 
 **Agents:** One `.md` file per agent in `agents/`. Required frontmatter: `name` (1–64 lowercase alphanumeric + hyphens), `description` (≤ 1024 chars). Body is the agent system prompt.
 
@@ -306,9 +294,9 @@ A plugin whose MCP server is its own npm package writes an unpinned invocation
 
 | Scope | Claude Code | Cursor | Codex |
 | --- | --- | --- | --- |
-| **Personal** | `~/.claude/plugins/local/<name>` symlink | `~/.cursor/plugins/local/<name>` symlink + reload | `~/.agents/plugins/marketplace.json` |
+| **Personal** | `universal-plugin plugin install`, then restart | `universal-plugin plugin install` (copies), then reload the window | `~/.agents/plugins/marketplace.json` |
 | **Team** | npm private package | Cursor Teams admin import | `.agents/plugins/marketplace.json` in repo |
-| **Public** | PR to `anthropics/claude-plugins-official` | `cursor.com/marketplace/publish` | `codex plugin marketplace add` |
+| **Public** | `anthropics/claude-plugins-official` is curated and takes no pull requests; check its submission route live (`publish-plugin`, step 0c) | `cursor.com/marketplace/publish` | `codex plugin marketplace add` |
 
 Default scope: **team**.
 
@@ -318,13 +306,11 @@ Default scope: **team**.
 
 - Using `../` in any manifest-declared path
 - Hardcoding absolute paths instead of `${PLUGIN_ROOT}` or `${PLUGIN_DATA}`
-- Committing `mcp.json` as a regular file — must always be a symlink to `.mcp.json`
 - Hand-authoring vendor hook files — use canonical `hooks/hooks.json` and let build generate vendor versions
 - Relying on extended component types (commands, rules, agents, hooks) for core functionality — silently ignored on non-supporting hosts
 - Duplicating SKILL.md content in `plugin.json` — the manifest is a path index, never a content mirror
 - Using `rules/` for cross-agent always-on guidance — use AGENTS.md instead
 - Putting role- or task-scoped guidance in always-on context (`rules/` or AGENTS.md) — make it a reference loaded on demand
-- Putting install-time metadata in `plugin.json` instead of `skill.json`
 
 ## Cross-Platform Portability
 
@@ -338,7 +324,7 @@ Default scope: **team**.
 | Windsurf | Needs conversion | 6,000 char/file hard limit; 12,000 chars total |
 | Zed, Aider, Continue.dev, Cline | No | Incompatible formats |
 
-Portability rules for skill bodies: keep each `SKILL.md` body under 6,000 chars; use forward slashes in path references; declare environment requirements in `compatibility` frontmatter; do not embed vendor-specific syntax in skill bodies.
+Portability rules for skill bodies: for a skill that must load in Windsurf, keep the `SKILL.md` body under its 6,000-char limit and move detail into `references/`; use forward slashes in path references; declare environment requirements in `compatibility` frontmatter; do not embed vendor-specific syntax in skill bodies.
 
 ## References
 

package/references/slash-invocation.md

@@ -10,7 +10,7 @@ description: Deploy the application after running release checks.
 invocation-policy: user
 ---
 
-Deploy $ARGUMENTS.
+Deploy the environment the user names in the invocation.
 ```
 
 | Policy | Meaning | Default |
@@ -22,7 +22,7 @@ Deploy $ARGUMENTS.
 `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.
+- Cursor uses the same `SKILL.md` and its native invocation flag; no per-skill command is derived.
 - 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.
 

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.3","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.1","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.3`), 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.1`), 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.
@@ -132,8 +132,7 @@ Validation runs before the first write, so a failed build leaves the tree untouc
 - **Expect a build to pin skill `npx` references or decide a version.** Build derives and copies
   whatever `plugin.json` carries. Stamping is the release-time `plugin version`, not this step.
 - **Expect a build to copy governances into skills.** A skill loads a reference through the
-  `reference` skill in the `cyber-agentkit` plugin; the build does not copy them and has no
-  `--check` flag.
+  `reference` skill in the `cyber-agentkit` plugin; the build does not copy them.
 
 ## Related skills
 

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.3","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.1","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/README.md

@@ -35,7 +35,7 @@ on purpose, so it folds into that command rather than competing with it.
 ## Boundaries
 
 Diagnoses the plugin a project ships. A repository's own agent wiring — `.agents/skills/`,
-`AGENTS.md`, per-harness bridges — is `buddy-agent-harness:doctor`.
+`AGENTS.md`, per-harness bridges — is `buddy-agent-harness:doctor-buddy-agent-harness`.
 
 ## References
 

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

@@ -143,7 +143,7 @@ user can run, or ask before running it yourself.
 
 ## Version drift
 
-A version lives in five places. Two are authored: the canonical `plugin.json`, and the `package.json`
+A version lives in six places. Two are authored: the canonical `plugin.json`, and the `package.json`
 at the `packagePath` the CLI reports (`config get --key packagePath`), resolved from the plugin root.
 The rest are stamped from them by `plugin version`: the vendor manifests, this plugin's entry in each
 repository catalog, the `npx`/`upx <package>@<version>` pins in the skills, and each `mcpServers`
@@ -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.3`, pinned. This check matters most where the release tool picks the
+`npx universal-plugin@0.17.1`, pinned. This check matters most where the release tool picks the
 number, because nothing else runs between that bump and publish.
 
 ## Unreleased content
@@ -203,7 +203,7 @@ is meant to ship — content that is still being worked on is not a finding to a
   directly. Its **components** are a separate question — a `copilot-root-components` finding is a real
   fault, and `canonical` is only healthy for a plugin that declares none of the moved kinds.
 - Do not treat repo-private agent configuration (`.claude/skills/`, `.agents/skills/`) as part of the
-  plugin. Diagnosing a repository's own skill wiring is `buddy-agent-harness:doctor`.
+  plugin. Diagnosing a repository's own skill wiring is `buddy-agent-harness:doctor-buddy-agent-harness`.
 
 ## Related skills
 

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.3","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.1","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/README.md

@@ -47,7 +47,7 @@ hold everywhere belongs in the Markdown body. See `references/frontmatter.md`, w
 ## Boundaries
 
 Plugin authoring only. Setting a repository up to *consume* skills — `AGENTS.md`, the
-`.agents/skills/` layout, per-harness bridges — is `buddy-agent-harness:init`. This skill does not
+`.agents/skills/` layout, per-harness bridges — is `buddy-agent-harness:init-buddy-agent-harness`. This skill does not
 touch CI, repository settings, or unrelated project files.
 
 ## References

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

@@ -34,7 +34,7 @@ runtime you are enabling, and only those.
 
 This skill owns the **authoring** side: the plugin a project ships. Setting a repository up to
 *consume* skills — the `.agents/skills/` layout, `AGENTS.md`, per-harness bridges — is
-`buddy-agent-harness:init`, not this.
+`buddy-agent-harness:init-buddy-agent-harness`, not this.
 
 ## Prerequisites
 
@@ -240,7 +240,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 | Publish a packaged plugin to the marketplace | `publish-plugin` |
 | Bump the pinned `universal-plugin@<version>` the project *calls* (not the plugin's own version) | `upgrade-plugin` |
 | Rewrite `npx` pins to the `upx` runner | `adopt-upx` |
-| Set a repository up to *consume* skills (`AGENTS.md`, `.agents/skills/`) | `buddy-agent-harness:init` |
+| Set a repository up to *consume* skills (`AGENTS.md`, `.agents/skills/`) | `buddy-agent-harness:init-buddy-agent-harness` |
 
 ## References
 

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

@@ -34,7 +34,7 @@ entry in both `vendors` and `harnesses` under
 
 Infer from context; ask only if ambiguous. [`standard.md`](./standard.md) has the component table and
 the layout they go in; the `plugin-design` reference decides which component a given need calls
-for. The universal minimum is `skills/<name>/SKILL.md` plus `.mcp.json`.
+for. The universal minimum is `skills/<name>/SKILL.md` plus `mcp.json`.
 
 ## Step 4 — Scaffold
 
@@ -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.3`. Add `--npm` when an npm package ships the plugin,
+the pinned `npx universal-plugin@0.17.1`. 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).
@@ -83,10 +83,10 @@ delivery path at all.
 Run the mechanical validator from the aced **improve-skill** skill:
 
 ```bash
-node "<path to aced improve-skill>/scripts/validate.mts" --path skills/<skill-name>
+node "<path to aced improve-skill>/scripts/validate.mjs" --path skills/<skill-name>
 ```
 
-Fix every CRITICAL finding, then invoke the **audit-skill** skill for the full review.
+Fix every CRITICAL finding, then invoke the `aced:improve-skill` skill for the full review.
 [`frontmatter.md`](./frontmatter.md) covers what has to hold across runtimes.
 
 ## Step 7 — Build
@@ -98,8 +98,8 @@ npx universal-plugin plugin build
 Useful flags: `--dry-run` to see the plan, `--verbose` for field-by-field decisions, `--vendor <id>`
 for one target, `--clean` to delete derived manifests first.
 
-Read the warnings. An unknown vendor id, an undeliverable Copilot override, and a failed Codex prompt
-write all surface there rather than as errors.
+Read the warnings. An unknown vendor id and an undeliverable Copilot override both surface there
+rather than as errors.
 
 ## Step 8 — Install locally to test
 
@@ -113,7 +113,7 @@ restart for Claude Code, **Developer: Reload Window** for Cursor. `--list` shows
 without writing; `--vendor <id>` narrows it; `plugin uninstall` removes it again.
 
 Codex and Copilot CLI scan no local plugin directory, so they report as `unsupported`. Reach those
-through a repository-local marketplace — `publish-plugin`.
+through a repository-local marketplace — `marketplace`.
 
 Do not hand-write a symlink for this. The recipe that circulated for it named
 `~/.claude/plugins/local/`, which does not exist, and a symlink into Cursor's local directory is

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

@@ -40,7 +40,7 @@ Only a skill the project *distributes* belongs to a plugin.
 | `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | **No** — repo-private tooling |
 
 If the only skills are in private locations, say nothing about adoption. A repository that configures
-its own agents is not a plugin waiting to happen; `buddy-agent-harness:init` is the skill for that
+its own agents is not a plugin waiting to happen; `buddy-agent-harness:init-buddy-agent-harness` is the skill for that
 side of the line.
 
 ## Making the adoption offer

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

@@ -30,7 +30,7 @@ universal-plugin reads `invocation-policy` from each `SKILL.md` and projects it
 | --- | --- | --- |
 | `both` (default) | user- and model-invocable | nothing |
 | `user` | explicit invocation only | writes `disable-model-invocation: true` into the skill's frontmatter |
-| `model` | model-invocable only, not user-facing | writes `user-invocable: false`, and emits no Codex prompt |
+| `model` | model-invocable only, not user-facing | writes `user-invocable: false` |
 
 Two consequences worth knowing before you run a build:
 

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

@@ -58,7 +58,7 @@ what each build gets. A vendor listed in `vendors` with no `harnesses` entry sti
 ├── agents/<name>.md
 ├── rules/<name>.mdc         (Cursor-only guidance)
 ├── hooks/hooks.json
-├── .mcp.json
+├── mcp.json
 └── README.md
 ```
 
@@ -70,7 +70,7 @@ directories. Create the rest only when the plugin has content for them.
 | Component | Field | Directory | Reaches |
 |-----------|-------|-----------|---------|
 | Skills | `skills` | `skills/<name>/SKILL.md` | every vendor |
-| MCP servers | `mcpServers` | `.mcp.json` | every vendor |
+| MCP servers | `mcpServers` | `mcp.json` | every vendor |
 | Commands | `commands` | `commands/<name>.md` | Claude Code, Cursor, Copilot CLI |
 | Agents | `agents` | `agents/<name>.md` | Claude Code, Cursor, Copilot CLI |
 | Hooks | `hooks` | `hooks/hooks.json` | every vendor — authored PascalCase, translated per vendor by the build; handler types vary |
@@ -79,7 +79,7 @@ directories. Create the rest only when the plugin has content for them.
 | Output styles | `outputStyles` | `output-styles/` | Claude Code only |
 
 The universal minimum — reaching every runtime with no vendor manifest at all — is
-`skills/<name>/SKILL.md` plus `.mcp.json`. Reach for a narrower component only when the plugin needs
+`skills/<name>/SKILL.md` plus `mcp.json`. Reach for a narrower component only when the plugin needs
 what only that component does; the `plugin-design` reference is the authority on that choice.
 
 ## Constraints

package/skills/init-universal-plugin/references/vendors/copilot-cli.md

@@ -83,6 +83,9 @@ Do not build a delivery path for these into the plugin manifest. There is nothin
 
 ### Still open
 
+Open as of the 1.0.83 runtime examined above. Re-check against the current release before relying
+on any of these.
+
 - **Where the `unknown field (ignored)` warning surfaces.** It exists in the binary but reached no
   output on `plugin install`, `plugin list`, or `plugins list`. Likely the interactive dashboard or
   the session config-problems channel.

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.3","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.1","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