universal-plugin 0.9.0 → 0.10.0

package/skills/marketplace/SKILL.md

@@ -1,193 +1,82 @@
 ---
 name: marketplace
-description: Use this skill to let people install a plugin straight from its own repository — generate the local marketplace catalogs Claude Code, Codex, GitHub Copilot CLI, and Cursor read, and write the README install section that tells users what to type. Trigger on "set up a local marketplace", "let users install this from my repo", "generate marketplace catalogs", "add install instructions to the README", "how do people install this plugin", or "make this repo installable".
-argument-hint: '[--claude] [--codex] [--copilot] [--cursor] [--dry-run] [--force]'
+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]'
 ---
 
-# Local marketplace
+# marketplace
 
 A repository can carry its own catalog, so a user adds the repository as a marketplace and installs
 from it. No service, no submission, no account.
 
-All four runtimes read such a catalog. Three of them let a user add it; Cursor's reaches users when
-an admin imports the repository as a team marketplace.
+This skill is the front door to that catalog. It routes; the procedure lives in the reference the
+route names. Read only the one you need.
 
-| Runtime | Catalog it reads | What the user types |
-| --- | --- | --- |
-| Claude Code | `.claude-plugin/marketplace.json` | `/plugin marketplace add`, then `/plugin install` |
-| Codex | `.agents/plugins/marketplace.json`, or the Claude path | `codex plugin marketplace add`, then `codex plugin add` |
-| GitHub Copilot CLI | `.github/plugin/marketplace.json`, or the Claude path | `copilot plugin marketplace add`, then `copilot plugin install` |
-| Cursor | `.cursor-plugin/marketplace.json` | nothing; an admin imports the repository as a team marketplace |
-
-Read `references/runtimes.md` before writing any command into a README, and treat that file as the
-only source of install commands. The trap that lives there: Codex installs with `plugin add` where
-Copilot CLI uses `plugin install`.
-
-## Workflow
-
-### 1. Find what there is to list
-
-```bash
-ls plugins/*/plugin.json 2>/dev/null
-test -f plugin.json && cat plugin.json
-```
-
-`plugin init --vendor <id>` already registers the plugin it scaffolds in these catalogs, so a
-repository that has run it carries an entry before this skill starts. Read what is there first: this
-command regenerates a catalog from what it discovers, which is the whole repository rather than one
-plugin.
-
-A catalog lists plugins found at `<scan-root>/<plugin-dir>/plugin.json`, which defaults to
-`plugins/`. Pass `--plugin-scan-dir <dir>` when the repository keeps them elsewhere. A repository
-whose only plugin sits at its root has nothing to discover; say so rather than generating an empty
-catalog.
-
-Discovery reads a plugin's `name` and nothing else. A missing or malformed `name` stops the command
-before any write.
-
-### 2. Choose targets with the user
-
-Name the runtimes and what each one gets, using the table above. With no target flags the command
-selects all four.
-
-One catalog can serve two runtimes when the user wants fewer files: Codex reads the Claude catalog
-too, so `--claude` alone covers both. The reverse does not hold, because Claude Code rejects the
-Codex catalog for its missing `owner`. Generating both is the default, so each is idiomatic for its
-runtime.
-
-### 3. Generate
-
-```bash
-node scripts/marketplace.mjs --claude --copilot --dry-run
-```
-
-Resolve that path against this skill's own directory; `npx universal-plugin marketplace init` is the
-fallback. Run `--dry-run` first and show the plan. The command never prompts.
-
-Then generate for real. Selected targets compose as a union, so name every target you want each run.
-
-| Status | Means |
-| --- | --- |
-| `generated` | written |
-| `unchanged` | already correct, byte differences in key order and whitespace ignored |
-| `planned` | `--dry-run` only |
-| `empty` | nothing discovered for this target |
-
-A selected artifact that differs from what would be generated stops the whole run. That is the
-command protecting a hand-edited catalog. Read the difference, then re-run with `--force` only once
-you know what it discards.
-
-### 4. Validate every catalog
-
-A catalog the runtime rejects is worse than no catalog: it is found, read, and refused at install
-time, far from here. Never conclude this skill without running the check.
+## Routes
 
-```bash
-node scripts/validate.mjs
-```
-
-Resolve that path against this skill's own directory; `npx universal-plugin marketplace validate` is
-the fallback. It reads each catalog and checks it against the schema its runtime loads. Exit status is
-1 when any selected catalog is invalid, and every issue names the key and the value to write instead,
-on stderr:
-
-```
-error: catalog ".claude-plugin/marketplace.json" does not match the marketplace schema:
-  owner must be an object with a name, not string — write { "name": "Ari Vance" }
-  plugins[0].repository must be a string, not object — write "https://github.com/o/r.git"
-```
-
-| Status | Means |
-| --- | --- |
-| `valid` | loads in that runtime |
-| `invalid` | the runtime would refuse it; the issues say why |
-| `missing` | no catalog at that path, which is only a failure under `--required` |
-
-Fix an issue in the source it comes from, then regenerate: an entry's fields are derived from the
-plugin's `plugin.json`, so an npm-style `repository` object belongs fixed there. 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.
-
-The two checks the schema cannot make: `--required` for a target the user asked for, and sources on
-disk. Every `./` source is checked for existence by `validate`; sources resolve against the directory
-containing `.claude-plugin/`, and they do not resolve at all for a user who adds the marketplace by
-direct URL to the JSON file.
-
-### 5. Offer the README section
-
-Ask before writing. A README is the user's document, and this is an edit to it, not a new file.
-
-```bash
-node scripts/install-docs.mjs
-```
+| Route | Use it when | Procedure |
+| --- | --- | --- |
+| `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` |
+| `validate` | Check the catalogs the repository already carries against the schema each runtime loads. | `references/validate.md` |
 
-Stdout is one JSON object: `targets`, `repo`, and `markdown`. Insert `markdown` verbatim. It carries
-a section per generated catalog, built from the marketplace name and plugin names actually on disk.
+`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.
 
-Check `repoResolved` first. When it is `false` the repository slug could not be found and the
-snippet contains `<owner>/<repo>`; ask the user for the slug and re-run with `--repo <owner>/<repo>`
-rather than leaving a placeholder in their README.
+Both 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.
 
-If the README already has an install section, show the difference and let the user choose. Do not
-append a second one.
+## Intake
 
-### 6. Verify
+**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.
 
-Re-run the generator and confirm every selected target reports `unchanged`. Confirm each catalog
-path exists. State plainly that nothing was published: these files sit in the repository until a
-user adds it as a marketplace.
+**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`.
 
-A local path is the cheapest end-to-end proof:
+Discovery settles the question faster than the user can:
 
 ```bash
-codex plugin marketplace add "$(pwd)"
-codex plugin list
-codex plugin marketplace remove <marketplace-name>
+ls plugins/*/plugin.json 2>/dev/null
+ls .claude-plugin/marketplace.json .agents/plugins/marketplace.json 2>/dev/null
 ```
 
-`codex plugin list` prints the manifest path it read, which is what tells you the catalog was found
-rather than merely present. Offer this check rather than running it unasked: it writes to the user's
-Codex config. Remove what you added.
-
-## Local development against Codex
+Plugins under `plugins/` and no catalog yet is `init`. A catalog already there and nothing new on
+disk is usually `add`.
 
-Codex installs a **copy** of the plugin at
-`~/.codex/plugins/cache/<marketplace>/<plugin>/<version>`, where the version is the one the plugin's
-own manifest carries. Editing the plugin's files does not reach that copy.
+## Where each runtime looks
 
-After changing packaged files, install again and start a new session:
-
-```bash
-codex plugin add <plugin>@<marketplace>
-```
-
-That one command is the whole refresh: re-running it at the same version overwrites the cached copy
-with the current source, so neither `codex plugin remove` nor a version bump is needed. Codex reads
-the cache when a session starts, so the session you are in keeps the old copy — start a new one.
+| Runtime | Catalog it reads | What the user types |
+| --- | --- | --- |
+| Claude Code | `.claude-plugin/marketplace.json` | `/plugin marketplace add`, then `/plugin install` |
+| Codex | `.agents/plugins/marketplace.json`, or the Claude path | `codex plugin marketplace add`, then `codex plugin add` |
+| GitHub Copilot CLI | `.github/plugin/marketplace.json`, or the Claude path | `copilot plugin marketplace add`, then `copilot plugin install` |
+| Cursor | `.cursor-plugin/marketplace.json` | nothing; an admin imports the repository as a team marketplace |
 
-The catalog entry's version is derived from the canonical manifest, so a version move updates both
-(`/universal-plugin:version` owns that). Codex itself does
-not read the entry's version; keeping it true is this project's policy, so the catalog never states
-a version the plugin does not have.
+Three of the four read `.claude-plugin/marketplace.json`, so one file covers Claude Code, Codex, and
+Copilot CLI. The reverse does not hold: Claude Code rejects the Codex catalog for its missing
+`owner`.
 
-## Rules
+## Rules for every route
 
 - **Never publish a command that is not in `references/runtimes.md`.** An install command that fails
-  is worse than no install section. Widely-copied README snippets are not sources.
+  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
+  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
   supported directory. A file named anything else is invisible to it, whatever directory holds it.
-- **Do not write a Cursor install command.** Cursor has no command that adds a repository catalog;
-  a developer tests through `~/.cursor/plugins/local/<name>` and users get the plugin through a team
-  marketplace an admin imports.
-- **Never hand-author or hand-patch a catalog.** Generate it, then validate it. 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.
-- **Report the validation result, not just the generation result.** A run that generated four files
-  and validated none has not been verified.
-- **Ask before editing the README**, and before `--force` replaces a catalog the user may have
-  hand-edited.
-- This command publishes nothing and registers nothing. Say so in the report; a user who believes
-  they have published will not understand why nobody can install.
+- **Do not write a Cursor install command.** Cursor has no command that adds a repository catalog.
+- **Report the validation result, not just the write.** A run that wrote four files and validated
+  none has not been verified.
+- **Nothing here publishes or registers anything.** Say so in the report; a user who believes they
+  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/marketplace` repository is a different job: use
   `publish-plugin`.
 
@@ -202,8 +91,8 @@ a version the plugin does not have.
 
 ## References
 
+- `references/init.md` — derive the catalogs from the plugins this repository holds
+- `references/add.md` — list a plugin that lives elsewhere
+- `references/validate.md` — check the catalogs against the schema each runtime loads
 - `references/runtimes.md` — per-runtime install commands and their sources
-- The official Claude Code marketplace schema, which `validate` checks against:
-  <https://json.schemastore.org/claude-code-marketplace.json>
 - [Research conclusion](https://github.com/cyberuni/universal-plugin/blob/main/.research/local-marketplaces/conclusion.md)
-- [`marketplace init` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/init/README.md)

package/skills/marketplace/references/add.md

@@ -0,0 +1,138 @@
+# Route: add
+
+List a plugin that lives somewhere else — an npm package, a GitHub repository, or an entry another
+marketplace already publishes. This is what makes a repository a curated marketplace rather than
+only its own plugins' home.
+
+`init` covers the other case and the two compose; see `references/init.md`.
+
+## 1. Work out what the user is naming
+
+One positional argument says where the plugin lives. The command disambiguates by shape:
+
+| Form | Example | Source written |
+| --- | --- | --- |
+| path in this repository | `./plugins/alpha` | `"./plugins/alpha"` |
+| GitHub repository | `cyberuni/universal-plugin` | `{ "source": "github", "repo": "…" }` |
+| git or https URL | `https://example.com/o/r.git` | `{ "source": "url", "url": "…" }` |
+| npm package | `npm:repobuddy`, `@cyberuni/upx` | `{ "source": "npm", "package": "…" }` |
+| another marketplace | `repobuddy@cyberplace` | whatever source that marketplace publishes |
+
+Two shapes collide, and both have a flag that settles them:
+
+- **`plugins/alpha` reads as a GitHub repository**, not a directory — `owner/repo` and a relative
+  path are the same string. Write `./plugins/alpha`, or pass `--path`.
+- **A leading `@` is a scope, not a marketplace.** `@cyberuni/upx` is a package; `upx@cyberplace` is
+  a marketplace entry.
+
+`--path`, `--npm`, `--github`, `--url`, and `--from-marketplace` each force the reading. Pass one.
+
+### One plugin out of a monorepo
+
+`owner/repo` and a git URL both name a whole repository, and neither source form can say which
+directory inside it is the plugin. `--subdir` says it, which turns the source into `git-subdir`:
+
+```bash
+node scripts/add.mjs cyberuni/cyber-sdd --subdir plugins/aced
+# { "source": "git-subdir", "url": "https://github.com/cyberuni/cyber-sdd.git", "path": "plugins/aced" }
+```
+
+The entry is named for that directory — `aced` — not for the repository. Ask for `--subdir` whenever
+the user names a repository you know publishes more than one plugin; without it the entry points at
+the repository root, which installs the wrong thing rather than failing.
+
+`--ref <branch-or-tag>` and `--sha <commit>` pin a git source. Both apply to `url`, `github`, and
+`git-subdir` only: an npm package is pinned by version and a path is whatever is on disk. A `--sha`
+must be the full 40-character hash, which the schema requires.
+
+## 2. Choose targets, and know what will be skipped
+
+Not every runtime installs from every source. Only a repository path reaches all four:
+
+| Source | Claude Code | Codex | Copilot CLI | Cursor |
+| --- | --- | --- | --- | --- |
+| path | yes | yes | yes | yes |
+| npm | yes | yes | — | — |
+| github, url, git-subdir | yes | — | — | — |
+
+A target that cannot resolve the source is reported `skipped` with the reason, and no file is
+written for it. That is deliberate: a source a runtime refuses is an install failure in someone
+else's terminal. Say which targets were skipped and why — do not report "added" and leave the user
+to discover that two catalogs have no entry.
+
+With no target flags all four are selected, so the skips are the normal case for an npm package.
+
+## 3. Supply the metadata
+
+Nothing is fetched. The command reads what is already on this machine and takes the rest from flags:
+
+- a **path** source reads the plugin's own `plugin.json`
+- an **npm** source reads `node_modules/<pkg>/package.json` when the package happens to be installed
+- a **marketplace** entry brings the metadata that marketplace already publishes
+
+Flags fill or override the gaps: `--description`, `--version`, `--homepage`, `--repository`,
+`--license`, `--keywords` (comma-separated). Ask the user for a description at minimum; an entry
+with only a name tells a browsing user nothing.
+
+`--name` overrides the entry name, which otherwise comes from the spec: the package name without its
+scope, the repository name, or the directory name.
+
+## 4. Preview, then write
+
+```bash
+node scripts/add.mjs npm:repobuddy --description "Repo automation" --dry-run
+```
+
+Resolve that path against this skill's own directory; `npx universal-plugin marketplace add` is the
+fallback. Run `--dry-run` first and show the plan, including the skips. The command never prompts.
+
+| Status | Means |
+| --- | --- |
+| `added` | the entry was not listed; it is now |
+| `updated` | an entry of that name was listed and has been replaced |
+| `unchanged` | already says exactly this |
+| `planned` | `--dry-run` only |
+| `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.
+
+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
+repository curating other people's plugins usually has no root manifest, so `--owner` is the flag it
+needs.
+
+## 5. Resolving `<plugin>@<marketplace>`
+
+The catalog schema has no "from another marketplace" source, so the entry is **resolved and copied**
+rather than referenced. The marketplace has to be readable:
+
+- installed in the runtime already — read from `~/.claude/plugins`, no network
+- otherwise, `--from <dir>` naming a checkout of it
+
+A marketplace that is not installed stops the run and says so. Ask the user to add it in their
+runtime, or to point `--from` at a clone; do not guess a URL.
+
+An entry whose source is a `./` path is **rewritten**, not copied. That path resolves against the
+other marketplace's root, which this repository is not — but it is a location inside a repository
+whose URL is known, so it becomes an absolute source:
+
+| Entry in the other marketplace | Written here |
+| --- | --- |
+| `./plugins/aced` in `cyberuni/cyberplace` | `{ "source": "git-subdir", "url": "https://github.com/cyberuni/cyberplace.git", "path": "plugins/aced" }` |
+| `./` in `unional/skills` | `{ "source": "github", "repo": "unional/skills" }` |
+
+The origin comes from what the runtime recorded for that marketplace, falling back to the clone's
+own git remote — which is also how `--from` resolves one. A marketplace with neither stops the run:
+there is no URL to rewrite against, and a bare path would name a directory this repository does not
+have.
+
+Both rewritten forms are Claude Code source types, so expect Codex, Copilot CLI, and Cursor to be
+skipped for a subdirectory plugin.
+
+## 6. Validate
+
+Follow `references/validate.md`. The entry has to load in every runtime that got one.
+
+Then state plainly that nothing was published: the entry sits in the repository until a user adds it
+as a marketplace.

package/skills/marketplace/references/init.md

@@ -0,0 +1,131 @@
+# Route: init
+
+Derive a catalog from the plugins this repository holds, then offer the README section that tells
+users what to type.
+
+For a plugin that lives elsewhere, see `references/add.md`. The two compose on one repository.
+
+## 1. Find what there is to list
+
+```bash
+ls plugins/*/plugin.json 2>/dev/null
+test -f plugin.json && cat plugin.json
+```
+
+`plugin init --vendor <id>` already registers the plugin it scaffolds in these catalogs, so a
+repository that has run it carries an entry before this route starts. Read what is there first: this
+command regenerates a catalog from what it discovers, which is the whole repository rather than one
+plugin.
+
+A catalog lists plugins found at `<scan-root>/<plugin-dir>/plugin.json`, which defaults to
+`plugins/`. Pass `--plugin-scan-dir <dir>` when the repository keeps them elsewhere. A repository
+whose only plugin sits at its root has nothing to discover; say so rather than generating an empty
+catalog.
+
+Discovery reads a plugin's `name` and nothing else. A missing or malformed `name` stops the command
+before any write.
+
+## 2. Choose targets with the user
+
+Name the runtimes and what each one gets, using the table in `SKILL.md`. With no target flags the
+command selects all four.
+
+One catalog can serve two runtimes when the user wants fewer files: Codex reads the Claude catalog
+too, so `--claude` alone covers both. The reverse does not hold, because Claude Code rejects the
+Codex catalog for its missing `owner`. Generating both is the default, so each is idiomatic for its
+runtime.
+
+## 3. Generate
+
+```bash
+node scripts/marketplace.mjs --claude --copilot --dry-run
+```
+
+Resolve that path against this skill's own directory; `npx universal-plugin marketplace init` is the
+fallback. Run `--dry-run` first and show the plan. The command never prompts.
+
+Then generate for real. Selected targets compose as a union, so name every target you want each run.
+
+| Status | Means |
+| --- | --- |
+| `generated` | written |
+| `unchanged` | already correct, byte differences in key order and whitespace ignored |
+| `planned` | `--dry-run` only |
+| `empty` | nothing discovered for this target |
+
+A selected artifact that differs from what would be generated stops the whole run. That is the
+command protecting a hand-edited catalog. Read the difference, then re-run with `--force` only once
+you know what it discards.
+
+### What a regeneration keeps
+
+Discovery walks directories, so it can only speak for plugins that are in them. Two things survive a
+regeneration untouched:
+
+- an entry whose source is **not** a local path — an npm package, a GitHub repository — which only
+  `add` puts there
+- the source of a **discovered** plugin whose entry names a non-local source, with its derived
+  metadata refreshed around it
+
+So a plugin shipped through npm, whose repository path holds gitignored build output, keeps pointing
+at npm. What discovery owns it still owns: a local-path entry it no longer finds is dropped.
+
+## 4. Validate every catalog
+
+Follow `references/validate.md`. Never conclude without it.
+
+## 5. Offer the README section
+
+Ask before writing. A README is the user's document, and this is an edit to it, not a new file.
+
+```bash
+node scripts/install-docs.mjs
+```
+
+Stdout is one JSON object: `targets`, `repo`, and `markdown`. Insert `markdown` verbatim. It carries
+a section per generated catalog, built from the marketplace name and plugin names actually on disk.
+
+Check `repoResolved` first. When it is `false` the repository slug could not be found and the
+snippet contains `<owner>/<repo>`; ask the user for the slug and re-run with `--repo <owner>/<repo>`
+rather than leaving a placeholder in their README.
+
+If the README already has an install section, show the difference and let the user choose. Do not
+append a second one.
+
+## 6. Verify
+
+Re-run the generator and confirm every selected target reports `unchanged`. Confirm each catalog
+path exists. State plainly that nothing was published: these files sit in the repository until a
+user adds it as a marketplace.
+
+A local path is the cheapest end-to-end proof:
+
+```bash
+codex plugin marketplace add "$(pwd)"
+codex plugin list
+codex plugin marketplace remove <marketplace-name>
+```
+
+`codex plugin list` prints the manifest path it read, which is what tells you the catalog was found
+rather than merely present. Offer this check rather than running it unasked: it writes to the user's
+Codex config. Remove what you added.
+
+## Local development against Codex
+
+Codex installs a **copy** of the plugin at
+`~/.codex/plugins/cache/<marketplace>/<plugin>/<version>`, where the version is the one the plugin's
+own manifest carries. Editing the plugin's files does not reach that copy.
+
+After changing packaged files, install again and start a new session:
+
+```bash
+codex plugin add <plugin>@<marketplace>
+```
+
+That one command is the whole refresh: re-running it at the same version overwrites the cached copy
+with the current source, so neither `codex plugin remove` nor a version bump is needed. Codex reads
+the cache when a session starts, so the session you are in keeps the old copy — start a new one.
+
+The catalog entry's version is derived from the canonical manifest, so a version move updates both
+(`/universal-plugin:version` owns that). Codex itself does not read the entry's version; keeping it
+true is this project's policy, so the catalog never states a version the plugin does not have.

package/skills/marketplace/references/validate.md

@@ -0,0 +1,46 @@
+# Route: validate
+
+Check the catalogs the repository carries against the schema each runtime loads.
+
+Every route ends here. A catalog the runtime rejects is worse than no catalog: it is found, read,
+and refused at install time, far from the repository that wrote it. Never conclude the skill without
+running this.
+
+```bash
+node scripts/validate.mjs
+```
+
+Resolve that path against this skill's own directory; `npx universal-plugin marketplace validate` is
+the fallback. Exit status is 1 when any selected catalog is invalid, and every issue names the key
+and the value to write instead, on stderr:
+
+```
+error: catalog ".claude-plugin/marketplace.json" does not match the marketplace schema:
+  owner must be an object with a name, not string — write { "name": "Ari Vance" }
+  plugins[0].repository must be a string, not object — write "https://github.com/o/r.git"
+```
+
+| Status | Means |
+| --- | --- |
+| `valid` | loads in that runtime |
+| `invalid` | the runtime would refuse it; the issues say why |
+| `missing` | no catalog at that path, which is only a failure under `--required` |
+
+## Fixing what it reports
+
+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).
+
+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.
+
+Nothing is repaired automatically. A catalog edited by hand is the user's to correct.
+
+## The two checks the schema cannot make
+
+- `--required`, for a target the user asked for and did not get.
+- Sources on disk. Every `./` source is checked for existence. They resolve against the directory
+  holding `.claude-plugin/`, and they do not resolve at all for a user who adds the marketplace by
+  direct URL to the JSON file — which is the argument for a non-local source on a plugin
+  distributed that way (`references/add.md`).

package/skills/marketplace/scripts/add.mjs

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

package/skills/migrate-plugin/SKILL.md

@@ -175,9 +175,10 @@ Point every version and build step at the new plugin root:
 
 - Set the manifest extension's `packagePath` to `"."`.
 - `universal-plugin publish sync-version --root <pkg>` reads `packagePath` from
-  `<pkg>/.agents/universal-plugin.json`, not from the manifest extension. To use
-  it, create that file with `{ "packagePath": "." }`. If the repository instead
-  runs its own sync script, repoint that script's manifest path and leave it.
+  `<pkg>/.agents/universal-plugin.json`, not from the manifest extension. With
+  no `packagePath` it reads `<pkg>/package.json`, so a package that holds its
+  own plugin needs no config file for it. If the repository instead runs its
+  own sync script, repoint that script's manifest path and leave it.
 - Change every `universal-plugin plugin build --root <old>` in `package.json`
   scripts to the package directory, then run it and confirm it reports the
   vendor manifests as built and the catalog as unchanged or refolded.