universal-plugin 0.3.1 → 0.5.0

package/skills/init/references/create.md

@@ -0,0 +1,122 @@
+# Create a universal plugin
+
+Scaffold a new plugin from one canonical `plugin.json` and derive a manifest per chosen vendor.
+
+## Step 1 — Gather plugin identity
+
+Ask for what is missing. Every field lands at the canonical top level.
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | Yes | kebab-case, 1–64 chars, `a-z 0-9 - .` only |
+| `description` | Recommended | one sentence; **required** when targeting Codex |
+| `version` | If publishing | semver; **required** when targeting Codex |
+| `author.name` | Recommended | person or org name |
+| `homepage` | Optional | docs or landing page URL |
+| `repository` | Optional | source repo URL |
+| `license` | Optional | SPDX identifier, e.g. `MIT` |
+| `keywords` | Optional | discovery tags; array of strings |
+
+## Step 2 — Choose vendor targets
+
+Ask which runtimes to support; default to all four if the user is unsure. Each choice becomes an
+entry in both `vendors` and `harnesses` under
+`extensions["org.cyberuni.universal-plugin"]`.
+
+| Vendor ID | Derived manifest | Read before enabling |
+|-----------|------------------|----------------------|
+| `claude-code` | `.claude-plugin/plugin.json` | [`vendors/claude-code.md`](./vendors/claude-code.md) |
+| `cursor` | `.cursor-plugin/plugin.json` | [`vendors/cursor.md`](./vendors/cursor.md) |
+| `codex` | `.codex-plugin/plugin.json` | [`vendors/codex.md`](./vendors/codex.md) |
+| `copilot-cli` | none — reads root `plugin.json` | [`vendors/copilot-cli.md`](./vendors/copilot-cli.md) |
+
+## Step 3 — Choose components
+
+Infer from context; ask only if ambiguous. [`standard.md`](./standard.md) has the component table and
+the layout they go in; `governance show plugin-design` decides which component a given need calls
+for. The universal minimum is `skills/<name>/SKILL.md` plus `.mcp.json`.
+
+## Step 4 — Scaffold
+
+```bash
+node scripts/init.mjs --name <plugin-name> --vendor claude-code --vendor cursor --scaffold
+```
+
+Resolve `scripts/init.mjs` against this skill's directory; it runs the CLI that shipped beside it.
+`npx universal-plugin plugin init` is the fallback. Add `--npm` when an npm package ships the plugin,
+which also wires that `package.json`'s `files` to carry the derived manifests.
+
+`init` writes a minimal manifest — `$schema`, `name`, and the vendor list. Fill in the Step 1
+metadata and the `harnesses` overrides by hand afterwards; [`standard.md`](./standard.md) shows the
+finished shape.
+
+Then create the component files from `../assets/templates/`:
+
+| File to create | Template |
+|----------------|----------|
+| `skills/<name>/SKILL.md` | `assets/templates/skill.md` |
+| `commands/<name>.md` | `assets/templates/command.md` |
+| `agents/<name>.md` | `assets/templates/agent.md` |
+| `hooks/hooks.json` | `assets/templates/hooks.json` |
+| `commands/setup.md` (only with `rules/`) | `assets/templates/setup-command.md` |
+
+## Step 5 — Fill in the harness overrides
+
+Only fields one runtime understands go here; shared metadata stays at the top level. See each
+`vendors/<vendor>.md` for what that vendor accepts, and note that a `copilot-cli` entry has no
+delivery path at all.
+
+```json
+"harnesses": {
+  "claude-code": {},
+  "cursor": { "publisher": "<org>", "category": "<category>", "tags": ["<tag>"] },
+  "codex": { "interface": { "displayName": "<Human Name>", "category": "<category>" } },
+  "copilot-cli": {}
+}
+```
+
+## Step 6 — Audit the skills
+
+Run the mechanical validator from the aced **improve-skill** skill:
+
+```bash
+node "<path to aced improve-skill>/scripts/validate.mts" --path skills/<skill-name>
+```
+
+Fix every CRITICAL finding, then invoke the **audit-skill** skill for the full review.
+[`frontmatter.md`](./frontmatter.md) covers what has to hold across runtimes.
+
+## Step 7 — Build
+
+```bash
+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.
+
+## Step 8 — Install locally to test
+
+```bash
+npx universal-plugin plugin install
+```
+
+It installs into every runtime the manifest declares, linking where the runtime follows a symlink
+out of the tree and copying where it does not, and it prints the reload each one now needs — a
+restart for Claude Code, **Developer: Reload Window** for Cursor. `--list` shows where it would go
+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`.
+
+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
+rejected by Cursor's own scan.
+
+## Next
+
+Shipping it on npm → `migrate-plugin`. Listing it in a marketplace → `publish-plugin`. Releasing a
+number → `/universal-plugin:version`.

package/skills/init/references/detection.md

@@ -0,0 +1,62 @@
+# Detection
+
+What to look for during the survey, and where each finding belongs.
+
+```bash
+ls -d .claude-plugin .cursor-plugin .codex-plugin .github/plugin .plugin 2>/dev/null
+test -f plugin.json && cat plugin.json
+find . -name SKILL.md -not -path '*/node_modules/*' -not -path './.git/*'
+ls .mcp.json .lsp.json hooks/ commands/ agents/ rules/ output-styles/ 2>/dev/null
+```
+
+| What you find | What it means | Bucket |
+| --- | --- | --- |
+| root `plugin.json` with `$schema` on `agent-plugins.org` **and** an `extensions` object | already on the open standard | canonical |
+| `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/` manifest **below** a canonical root | build output | derived |
+| a vendor manifest with **no** canonical root `plugin.json` | a vendor-specific plugin | adoptable |
+| root `plugin.json` with neither `$schema` nor `extensions` | a legacy single-vendor manifest now sitting on the canonical path | adoptable |
+| publicly-shipped skills and no manifest of any kind | skills shipped without a plugin | adoptable |
+| `harnesses["copilot-cli"]` carrying fields | no delivery path — the canonical schema is closed | undeliverable |
+| `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | the project's own tooling | not a plugin |
+| `.github/plugin/plugin.json` | a path older builds wrote; shadowed by root and no longer generated | stale, safe to delete |
+
+For every vendor manifest found, record its path and **every field it sets**. Adoption reproduces
+all of it, and the Phase 5 diff is checked field by field.
+
+## Which skills count as public
+
+Only a skill the project *distributes* belongs to a plugin.
+
+| Location | Public? |
+|----------|---------|
+| `skills/<name>/SKILL.md` at the plugin root | Yes |
+| `<package>/skills/<name>/SKILL.md` where `package.json` `files` ships it | Yes |
+| `.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
+side of the line.
+
+## Making the adoption offer
+
+State what you found, what adoption buys, and let the user decline:
+
+> This project has a Claude Code plugin manifest but no canonical `plugin.json`. I can convert it to
+> the open Agent Plugins Specification, so one manifest drives Cursor, Codex, and Copilot CLI too —
+> Claude Code keeps working exactly as it does now. Want me to?
+
+Offer once. If the user declines, or their request was already something specific and unrelated
+(inspecting status, removing manifests), drop it and do what they asked.
+
+## Choosing vendors
+
+Ask which runtimes the plugin targets; default to all four when the user is unsure. Enabling a vendor
+costs a derived manifest and nothing else — except Codex, which additionally requires `version` and
+`description` on the canonical manifest and fails the build without them.
+
+Enabling Copilot CLI writes no file at all. Say so, rather than letting the user read a missing
+manifest as a broken build.
+
+Detecting a vendor directory means there is configuration to reconcile. It does not by itself mean
+the user wants that vendor maintained — say which vendors you are enabling and why, and let them
+correct the part that is actually variable.

package/skills/init/references/frontmatter.md

@@ -0,0 +1,65 @@
+# Skill frontmatter across runtimes
+
+A plugin's skills are the one component every runtime reads, so their frontmatter is where
+cross-vendor behavior is won or lost. Each runtime parses the fields it knows and silently drops the
+rest.
+
+## Required, everywhere
+
+```yaml
+---
+name: release-checklist
+description: Runs the release checklist. Use when cutting a release or publishing a package version.
+---
+```
+
+- `name` — 1–64 characters, lowercase letters, digits, hyphens. **Match the parent directory name**;
+  Claude Code resolves the command from the directory and treats `name` as a label, so matching them
+  removes the discrepancy.
+- `description` — say what the skill does *and* when to use it. This is the only text most runtimes
+  see when deciding whether to load it.
+
+Two failures actually cost you the skill: a missing `description`, and YAML that does not parse. The
+usual cause of the second is an unquoted colon — quote any description containing one.
+
+## `invocation-policy` — the field this build acts on
+
+universal-plugin reads `invocation-policy` from each `SKILL.md` and projects it per vendor:
+
+| Value | Meaning | What the build does |
+| --- | --- | --- |
+| `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 |
+
+Two consequences worth knowing before you run a build:
+
+- **The build rewrites the authored `SKILL.md`** to carry those flags. That file is both source and
+  artifact for this one field. Expect it in the diff; it is not a stray edit.
+- Any value other than `user`, `model`, or `both` **fails the build** rather than being ignored.
+
+## Which runtime understands which field
+
+| Field | Recognized by |
+| --- | --- |
+| `name`, `description` | all |
+| `license`, `metadata`, `compatibility` | accepted broadly, largely ignored |
+| `allowed-tools` | most |
+| `disable-model-invocation` | Claude Code, Cursor |
+| `context: fork`, `agent:` | Claude Code only |
+| `paths`, legacy `globs` | Cursor only |
+| `model` | Copilot CLI only |
+| `argument-hint`, `arguments` | Claude Code only |
+
+`argument-hint` and `arguments` are the one group that fails loudly rather than quietly: claude.ai
+uploads and the Skills API reject fields outside the standard set. A skill that takes arguments and
+also ships through those paths cannot use them — and does not need to, because no runtime but Claude
+Code substitutes anything anyway. Claude Code appends what the caller typed as `ARGUMENTS: <value>`
+when the body has no `$ARGUMENTS`, so a body that says how to read the invocation works everywhere,
+while a `$ARGUMENTS` placeholder resolves on one runtime and stays literal on the rest.
+
+## The rule that follows
+
+Anything that must hold on every runtime belongs in the Markdown body, not only in a vendor-specific
+field. The body is the one part every runtime reads. Treat vendor frontmatter as an optimization
+layered on instructions that already work without it.

package/skills/init/references/standard.md

@@ -0,0 +1,93 @@
+# The canonical baseline
+
+What every universal plugin has, before any vendor-specific work.
+
+## The one authored file
+
+Root `plugin.json`, on the Agent Plugins Specification v1.0.0 schema. Everything else a vendor reads
+is derived from it.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "One sentence saying what the plugin does.",
+  "author": { "name": "<author>" },
+  "extensions": {
+    "org.cyberuni.universal-plugin": {
+      "vendors": ["claude-code", "cursor", "codex", "copilot-cli"],
+      "skills": "./skills/",
+      "harnesses": {
+        "claude-code": {},
+        "cursor": {},
+        "codex": {},
+        "copilot-cli": {}
+      }
+    }
+  }
+}
+```
+
+The spec's top level holds the shared metadata. Everything universal-plugin needs to run a build
+lives under one namespaced key, `extensions["org.cyberuni.universal-plugin"]`:
+
+| Key | Holds |
+| --- | --- |
+| `vendors` | the build targets. When absent, the `harnesses` keys are the targets |
+| `harnesses` | per-vendor overrides, keyed by vendor id. `{}` opts in with no overrides |
+| `packagePath` | the npm package whose `package.json` carries the same version |
+| component paths (`skills`, `commands`, `agents`, `hooks`, …) | where each component lives |
+| `dependencies` | the plugins this plugin needs. Only Claude Code reads them; see [`vendors/claude-code.md`](./vendors/claude-code.md) |
+
+`vendors` and `harnesses` are separate on purpose: `vendors` says what to build, `harnesses` says
+what each build gets. A vendor listed in `vendors` with no `harnesses` entry still builds; a
+`harnesses` entry with no `vendors` list builds only while `vendors` is absent.
+
+## Directory layout
+
+```
+<plugin-root>/
+├── plugin.json              ← canonical definition (source of truth)
+├── skills/<name>/SKILL.md
+├── commands/<name>.md
+├── agents/<name>.md
+├── rules/<name>.mdc         (Cursor-only guidance)
+├── hooks/hooks.json
+├── .mcp.json
+└── README.md
+```
+
+`plugin init --scaffold` creates the standard `skills/`, `agents/`, `governances/`, and `commands/`
+directories. Create the rest only when the plugin has content for them.
+
+## Components
+
+| Component | Field | Directory | Reaches |
+|-----------|-------|-----------|---------|
+| Skills | `skills` | `skills/<name>/SKILL.md` | 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 |
+| LSP servers | `lspServers` | `.lsp.json` | Claude Code, Cursor |
+| Rules | `rules` | `rules/<name>.mdc` | Cursor only |
+| 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
+what only that component does; `governance show plugin-design` is the authority on that choice.
+
+## Constraints
+
+- **Never hand-edit a derived manifest.** `plugin build` owns `.claude-plugin/plugin.json` and its
+  siblings; an edit there survives until the next build and no longer.
+- **Never hand-edit a `version` field.** That move belongs to `/universal-plugin:version`.
+- **The canonical schema is closed.** A vendor-only field cannot be added at the top level; it goes
+  under that vendor's `harnesses` entry or nowhere.
+- Root `plugin.json` is not a build artifact. It is both the source of truth and the file Copilot CLI
+  reads, so deleting it takes out both.
+
+## Next
+
+Read only the `vendors/<vendor>.md` files for the runtimes being enabled. `SKILL.md` has the table.

package/skills/init/references/update.md

@@ -0,0 +1,31 @@
+# Update a universal plugin
+
+Change which vendors or components an existing plugin declares. Every path ends with a rebuild:
+
+```bash
+npx universal-plugin plugin build
+```
+
+## Add a vendor
+
+1. Add the vendor id to `extensions["org.cyberuni.universal-plugin"].vendors` in root
+   `plugin.json`, and add its key to `extensions["org.cyberuni.universal-plugin"].harnesses`.
+2. Populate vendor-specific fields — see that vendor's [`vendors/<vendor>.md`](./vendors/).
+3. If the vendor requires extra fields (`codex`: `version`, `description`), add them to the canonical
+   top level first — the build fails loudly without them.
+4. Rebuild for the new vendor: `plugin build --vendor <id>`.
+
+## Remove a vendor
+
+1. Remove the vendor id from `extensions["org.cyberuni.universal-plugin"].vendors` and its key from
+   `harnesses`.
+2. Delete the generated manifest at its output path. `copilot-cli` has none — removing it is a
+   manifest edit and nothing else.
+
+## Add or remove a component
+
+1. Add or remove the component field under `extensions["org.cyberuni.universal-plugin"]` in root
+   `plugin.json` (e.g. `"commands": "./commands/"`). [`standard.md`](./standard.md) has the component
+   table and which runtimes each one reaches.
+2. Scaffold or delete the corresponding files.
+3. Rebuild to regenerate all vendor manifests.

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

@@ -0,0 +1,76 @@
+# Claude Code
+
+Reads `.claude-plugin/plugin.json`. **The build derives it** — never hand-edit it.
+
+```bash
+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
+`extensions["org.cyberuni.universal-plugin"].harnesses["claude-code"]` sets. `$schema`, `extensions`,
+`vendors`, `packagePath`, and `harnesses` are universal-plugin's own orchestration — they never
+appear in a vendor manifest.
+
+An empty `"claude-code": {}` is the normal case: it opts into the build with no overrides.
+
+## Extra requirements
+
+None beyond `name`. Claude Code loads a manifest that carries only the shared metadata.
+
+## Skills
+
+Claude Code reads the skills the manifest's `skills` path names. The build additionally rewrites each
+`SKILL.md`'s frontmatter when the skill declares `invocation-policy` — `disable-model-invocation:
+true` for `user`, `user-invocable: false` for `model`. See [`../frontmatter.md`](../frontmatter.md).
+
+## Hooks
+
+Author hooks once, in canonical form: **PascalCase** event names (`SessionStart`, `PreToolUse`,
+`PostToolUse`, `Stop`, `UserPromptSubmit`) over Claude Code's matcher-group shape. That is what the
+canonical schema admits, and `plugin build` derives the rest (ADR-0011).
+
+Claude Code and Codex read that form as authored. Copilot CLI accepts it too — PascalCase selects its
+Claude-compatible payload format. Cursor is the one vendor translated: it gets
+`.cursor-plugin/hooks.json` with camelCase events, `"version": 1`, and each matcher group flattened
+into one entry per handler, and its derived manifest points there.
+
+**A handler type the vendor cannot run is dropped, and the build warns.** Claude Code runs `command`,
+`http`, `prompt`, and `agent`; Codex runs `command` only; Cursor runs `command` and `prompt`; Copilot
+CLI runs `command`, `http`, and `prompt`. Read the warnings — a plugin whose only `SessionStart`
+handler is `http` reaches Claude Code and Copilot CLI and nothing else. Copilot CLI reads the
+canonical file directly, so its unsupported handlers are reported as ignored at runtime rather than
+dropped from a derived file.
+
+Source: `.research/hook-event-survey/conclusion.md` (re-verified August 2026) — re-verify against
+vendor docs before relying on it.
+
+## Dependencies
+
+Claude Code is the only runtime that reads a plugin dependency, and it acts on one: it installs a
+missing dependency, enables it alongside the plugin that needs it, prunes it once nothing needs it,
+and refuses to load a plugin whose declared range the installed version does not satisfy. Declare it
+once, canonically, under `extensions["org.cyberuni.universal-plugin"].dependencies` — not under
+`harnesses["claude-code"]` (ADR-0013):
+
+```json
+"dependencies": ["cyber-asana", { "name": "cyber-notion", "marketplace": "cyberuni", "version": "^0.9.0" }]
+```
+
+A bare name resolves against the declaring plugin's own marketplace; `marketplace` picks another one,
+which the root marketplace must have allowed. Put a range in the object form — a range written as
+`"cyber-asana@^0.9.0"` is accepted and then discarded by the runtime, and the build warns and names
+the object to write instead.
+
+Cursor, Codex, and Copilot CLI read no such field. The build leaves it out of their manifests and
+warns; the build stays green. A plugin that loads there without its dependency is worth a line in
+your README.
+
+Source: `.research/plugin-schema/` (re-verified August 2026 against Claude Code 2.1.235) — re-verify
+against vendor docs before relying on it.
+
+## Leave alone
+
+Output styles are Claude Code-only, and hook blocks in `.claude/settings.json` are settings, not
+plugin content. Report them; do not convert them.

package/skills/init/references/vendors/codex.md

@@ -0,0 +1,56 @@
+# Codex
+
+Reads `.codex-plugin/plugin.json`. **The build derives it** — never hand-edit it.
+
+```bash
+npx universal-plugin plugin build --vendor codex
+```
+
+## Extra requirements — the build enforces these
+
+Targeting Codex requires `version` **and** `description` on the canonical manifest. Without either,
+`plugin build` fails loudly and writes nothing:
+
+```
+plugin.json validation failed:
+  - description is required when targeting codex
+  - version is required when targeting codex
+```
+
+The check is scoped to the vendors actually being built, so a Codex block that is not a selected
+target never blocks a build of the others.
+
+## Vendor-specific fields
+
+Codex's presentation metadata goes under its `harnesses` entry:
+
+```json
+"codex": {
+  "interface": {
+    "displayName": "<Human Name>",
+    "category": "<category>"
+  }
+}
+```
+
+## Skills
+
+For every skill that is not `invocation-policy: model`, the build also writes
+`~/.codex/prompts/<name>.md` — the skill body, as a Codex prompt.
+
+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.
+
+## Hooks
+
+Codex hook events are **PascalCase**, like Claude Code's, so the canonical file reaches Codex as
+authored. Codex runs `command` handlers only — an `http`, `prompt`, or `agent` handler is dropped
+from `.codex-plugin/hooks.json` with a warning. See [`claude-code.md`](./claude-code.md).
+
+## Dependencies
+
+Codex reads no plugin dependency. A declaration is left out of `.codex-plugin/plugin.json` with a
+build warning — deliberately, because the validator Codex ships for its plugin ingestion contract
+rejects any field outside its allowlist, and one unaccepted key fails the whole manifest. See
+[`claude-code.md`](./claude-code.md).

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

@@ -0,0 +1,53 @@
+# GitHub Copilot CLI
+
+Reads the **canonical root `plugin.json` directly**. The build derives nothing for it and writes no
+file — `plugin build` reports it with status `canonical`, which is success, not a skipped target.
+
+## Why nothing is derived
+
+Copilot CLI searches four paths and takes the first match:
+
+```
+.plugin/plugin.json → plugin.json → .github/plugin/plugin.json → .claude-plugin/plugin.json
+```
+
+Root `plugin.json` — the canonical manifest — is second, so it always shadows the two below it. It
+has consumed Open Plugin Spec v1 manifests since v1.0.74, so it already serves the canonical manifest
+as-is.
+
+Earlier builds wrote `.github/plugin/plugin.json`. That path loses to root by construction and was
+never read; a leftover copy is stale and safe to delete.
+
+## Vendor-specific fields cannot be delivered
+
+A `harnesses["copilot-cli"]` entry has nowhere to go. The canonical schema is closed
+(`additionalProperties: false`), so a Copilot-only field cannot ride along in root, and there is no
+derived file to put it in. The build warns:
+
+```
+harnesses.copilot-cli sets category, tags, but copilot-cli reads the canonical plugin.json
+directly — these fields are not delivered
+```
+
+Treat that warning as a decision to make, not noise: either the field belongs to a vendor that has a
+derived manifest, or it does not ship. Do not invent a path for it.
+
+## Do not
+
+- **Do not delete root `plugin.json` to "clean up" a Copilot target.** It is the source of truth and
+  the Copilot manifest at once.
+- Do not write `.plugin/plugin.json`. It outranks root, so it would silently shadow the canonical
+  manifest with a copy nothing regenerates.
+
+## Hooks
+
+Copilot CLI accepts **either casing**, and the casing selects the payload format: PascalCase gets the
+Claude-compatible format, so the canonical file reaches Copilot CLI unchanged. Because Copilot CLI
+reads that file directly, the build derives nothing for it — an `agent` handler is reported as ignored
+at runtime rather than dropped. See [`claude-code.md`](./claude-code.md).
+
+## Dependencies
+
+Copilot CLI reads no plugin dependency. Because it reads the canonical manifest directly, there is no
+derived file to leave the declaration out of — it sits under `extensions`, which Copilot CLI ignores,
+and the build reports it as ignored at runtime. See [`claude-code.md`](./claude-code.md).

package/skills/init/references/vendors/cursor.md

@@ -0,0 +1,52 @@
+# Cursor
+
+Reads `.cursor-plugin/plugin.json`. **The build derives it** — never hand-edit it.
+
+```bash
+npx universal-plugin plugin build --vendor cursor
+```
+
+## Extra requirements
+
+None beyond `name`.
+
+## Vendor-specific fields
+
+Cursor's catalog metadata goes under its `harnesses` entry, not at the canonical top level:
+
+```json
+"cursor": {
+  "publisher": "<org>",
+  "category": "<category>",
+  "tags": ["<tag>"]
+}
+```
+
+## Skills
+
+Cursor reads `SKILL.md` straight from the path the manifest's `skills` field names, and lets the user
+invoke a skill by typing `/` and searching for it. **The build derives no per-skill artifact for
+Cursor** — a mirrored `.cursor/commands/*.md` would be a second copy of the same body. Explicit-only
+invocation is expressed natively through `disable-model-invocation`, which the build already writes
+into the shared `SKILL.md`.
+
+## Rules are Cursor-only
+
+`rules/<name>.mdc` reaches Cursor and nothing else. Reach for a rule only when the plugin genuinely
+needs always-on guidance in Cursor; anything a task can load on demand belongs in a skill, where every
+runtime sees it. `governance show plugin-design` is the authority on that call.
+
+`.mdc` and `.md` are not interchangeable, and path-scoping has no equivalent in the other runtimes —
+never generate rules from a skill or a skill from a rule.
+
+## Hooks
+
+Cursor hook events are **camelCase** (`sessionStart`), and Cursor's hooks file differs in shape as
+well as casing. The build derives `.cursor-plugin/hooks.json` from the canonical file — never author
+it by hand. Cursor runs `command` and `prompt` handlers; an `http` or `agent` handler is dropped with
+a warning. See [`claude-code.md`](./claude-code.md).
+
+## Dependencies
+
+Cursor reads no plugin dependency. A declaration is left out of `.cursor-plugin/plugin.json` with a
+build warning. See [`claude-code.md`](./claude-code.md).

package/skills/init/scripts/init.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Runs `universal-plugin plugin init` from the CLI that ships beside this skill, so a scaffold
+// 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/init.mjs: four levels up is the package root.
+const packageRoot = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
+
+process.argv.splice(2, 0, 'plugin', 'init')
+await import(join(packageRoot, 'bin', 'universal-plugin.mjs'))

package/skills/marketplace/README.md

@@ -0,0 +1,38 @@
+# marketplace skill
+
+Make a repository installable on its own terms: generate the marketplace catalogs the runtimes read,
+then write the README section that tells users what to type.
+
+## What it does
+
+`marketplace init` discovers the plugins under `plugins/` and derives one catalog per selected
+runtime. This skill picks the targets with the user, runs the generation, verifies it, and offers
+the install documentation that goes with it.
+
+Nothing is published. The catalogs sit in the repository until someone adds it as a marketplace.
+
+## Support is uneven, and the skill says so
+
+| Runtime | Reality |
+| --- | --- |
+| Claude Code | a catalog plus two documented commands; works end to end |
+| GitHub Copilot CLI | same, with `copilot plugin marketplace add` |
+| Codex | a catalog plus `codex plugin marketplace add` and `codex plugin add`, both shipped and undocumented; works end to end |
+| Cursor | a catalog Cursor reads, but no command that adds it locally; users get it through a team marketplace an admin imports |
+
+`references/runtimes.md` is the only source of install commands, and every command in it carries an
+evidence ID. That constraint exists because the obvious way to write an install section is to copy
+one from another project's README, and two of the four commands in the README that prompted this
+skill are not in any vendor documentation.
+
+## The README half
+
+`scripts/install-docs.mjs` reads the catalogs on disk and emits the section as JSON, so the
+marketplace name, the plugin names, and the repository slug come from the repository rather than
+from a model retyping them. The skill asks before editing the README, because it is the user's
+document.
+
+## References
+
+- [Research: local marketplaces](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)