dsh-agent-plugins-market 0.6.0 → 0.6.2

package/schemas/codex/plugin.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/codex/plugin.schema.json",
+  "title": "Codex Plugin Manifest (legacy .codex-plugin dialect)",
+  "description": "Codex reads four manifest paths in order: root plugin.json when it declares the agent-plugins.org v1.0.0 $schema, then .codex-plugin/plugin.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json. This schema describes the legacy nested dialect; root plugin.json is validated by the vendored agent-plugins.org schema in schemas/1.0.0/plugin.schema.json. Authored from the OpenAI Codex source; OpenAI publishes no JSON Schema for the legacy dialect.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Sources: openai/codex codex-rs/core-plugins/src/manifest.rs, codex-rs/utils/plugins/src/plugin_namespace.rs, codex-rs/exec-server-protocol/src/protocol.rs (DISCOVERABLE_PLUGIN_MANIFEST_PATHS), and the bundled plugin-creator skill (plugin-json-spec.md, validate_plugin.py). The runtime deserializer and the scaffold validator disagree: the runtime reads hooks and commands, while validate_plugin.py rejects both. Fields the runtime reads are marked; interface is required by the scaffold validator only.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Plugin identifier. Falls back to the plugin-root directory name when absent. Runtime pattern: [A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*."
+    },
+    "id": { "type": "string", "description": "Accepted by the scaffold validator only; not read by the runtime deserializer." },
+    "version": { "type": "string", "description": "Semantic version. The scaffold validator requires it; the runtime defaults to None. Cachebuster form: <base>+codex.<token>." },
+    "description": { "type": "string" },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "url": { "type": "string", "description": "Must be an absolute https:// URL per the scaffold validator." }
+      },
+      "required": ["name"],
+      "additionalProperties": true
+    },
+    "homepage": { "type": "string" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": { "type": "array", "items": { "type": "string" }, "default": [] },
+    "skills": { "$ref": "#/$defs/pathList", "description": "Relative ./ paths to skill directories or files. Supplements default discovery rather than replacing it." },
+    "mcpServers": {
+      "description": "A path to an MCP configuration file, or an inline server map. The scaffold validator requires a path that normalizes to exactly .mcp.json; mcp.json without the dot is not accepted.",
+      "anyOf": [{ "type": "string" }, { "type": "object" }]
+    },
+    "apps": {
+      "type": "string",
+      "description": "Path to a .app.json file. Must exist when declared; the file must contain {\"apps\": {\"<key>\": {\"id\": string, \"category\"?: string}}}."
+    },
+    "hooks": {
+      "description": "Path(s) to hooks file(s) or inline hook configuration. Read by the runtime; rejected by the scaffold validator.",
+      "anyOf": [{ "type": "string" }, { "type": "array" }, { "type": "object" }]
+    },
+    "commands": { "$ref": "#/$defs/pathList", "description": "Read by the runtime for install-time command-to-skill migration; rejected by the scaffold validator." },
+    "interface": {
+      "type": "object",
+      "description": "UI and listing block. Required by the scaffold validator; optional for the runtime.",
+      "properties": {
+        "displayName": { "type": "string" },
+        "shortDescription": { "type": "string" },
+        "longDescription": { "type": "string" },
+        "developerName": { "type": "string" },
+        "category": { "type": "string" },
+        "capabilities": { "type": "array", "items": { "type": "string" }, "default": [] },
+        "websiteURL": { "type": "string" },
+        "websiteUrl": { "type": "string", "description": "Alias of websiteURL." },
+        "privacyPolicyURL": { "type": "string" },
+        "termsOfServiceURL": { "type": "string" },
+        "defaultPrompt": {
+          "description": "Starter prompts. At most 3 are used; each is truncated at 128 characters.",
+          "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+        },
+        "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+        "composerIcon": { "type": "string", "description": "Asset path; must be a real file in the archive." },
+        "logo": { "type": "string" },
+        "logoDark": { "type": "string" },
+        "screenshots": { "type": "array", "items": { "type": "string" }, "description": "PNG only, under ./assets/.", "default": [] }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "pathList": {
+      "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    }
+  }
+}

package/schemas/codex/spec.md

@@ -0,0 +1,91 @@
+# Codex plugin and marketplace specification
+
+Reference contract for Codex plugin repositories. Machine-readable companion: [marketplace.schema.json](marketplace.schema.json). The legacy nested manifest is described by [plugin.schema.json](plugin.schema.json); root `plugin.json` is validated by the vendored agent-plugins.org schema in [../1.0.0/plugin.schema.json](../1.0.0/plugin.schema.json).
+
+- **Verified:** 2026-09-08 against the `openai/codex` source.
+- **Evidence:** `codex-rs/core-plugins/src/manifest.rs` and `marketplace.rs`, `codex-rs/utils/plugins/src/plugin_namespace.rs`, `codex-rs/exec-server-protocol/src/protocol.rs`, `codex-rs/core-plugins/src/{installed_marketplaces,marketplace_add/source}.rs`, `codex-rs/cli/src/plugin_cmd.rs`, and the bundled `plugin-creator` skill (`plugin-json-spec.md`, `validate_plugin.py`). OpenAI's prose documentation (`developers.openai.com/plugins/build/plugins`) returns HTTP 403 to automated fetch, so every fact here rests on source.
+- **Upstream JSON Schema:** none for the legacy manifest or the marketplace manifest. Root `plugin.json` uses the published agent-plugins.org v1.0.0 schema.
+
+## Plugin manifest paths and precedence
+
+First match wins:
+
+| #   | Path                         | Dialect                                                                                            |
+| --- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| 1   | `plugin.json`                | Agent Plugins, only when `$schema` is `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json` |
+| 2   | `.codex-plugin/plugin.json`  | Legacy                                                                                             |
+| 3   | `.claude-plugin/plugin.json` | Legacy                                                                                             |
+| 4   | `.cursor-plugin/plugin.json` | Legacy                                                                                             |
+
+A symlinked root `plugin.json` is rejected. When path 1 wins, Codex also reads `.codex-plugin/plugin.json` as an **overlay** and takes only its `apps`, `hooks`, and `interface` values.
+
+In the Agent Plugins dialect Codex hard-codes the component locations `./skills` and `./mcp.json` (no leading dot) and accepts only `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions`; `repository` and `license` are parsed and discarded, and only the `com.openai` namespace of `extensions` is read.
+
+## Legacy manifest fields (`.codex-plugin/plugin.json`)
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | string | Falls back to the directory name; runtime pattern `[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*`. |
+| `id` | string | Scaffold validator only; not read by the runtime. |
+| `version` | string | Required by the validator; cachebuster form `<base>+codex.<token>`. |
+| `description`, `homepage`, `repository`, `license` | string |  |
+| `author` | `{name, email?, url?}` | `name` required by the validator; `url` must be absolute `https://`. |
+| `keywords` | string[] |  |
+| `skills` | string \| string[] | Supplements default discovery. |
+| `mcpServers` | string \| object | The validator requires a path normalizing to exactly `.mcp.json`; `mcp.json` without the dot is rejected. |
+| `apps` | string | Path to `.app.json`, containing `{"apps": {"<key>": {"id", "category"?}}}`. |
+| `hooks` | string \| string[] \| object \| object[] | Read by the runtime; rejected by the scaffold validator. |
+| `commands` | string \| string[] | Read by the runtime for command-to-skill migration; rejected by the validator. |
+| `interface` | object | Required by the validator: `displayName`, `shortDescription`, `longDescription`, `developerName`, `category`, `capabilities`, `defaultPrompt` (max 3 entries, 128 chars each). Optional: `websiteURL`/`websiteUrl`, `privacyPolicyURL`, `termsOfServiceURL`, `brandColor` (`#RRGGBB`), `composerIcon`, `logo`, `logoDark`, `screenshots` (PNG under `./assets/`). |
+
+The runtime deserializer and the scaffold validator disagree (tracked upstream as `openai/codex#27141`).
+
+## Marketplace manifest paths and precedence
+
+First match wins: `.agents/plugins/marketplace.json` → `.agents/plugins/api_marketplace.json` → `.claude-plugin/marketplace.json` → `.cursor-plugin/marketplace.json`.
+
+`~/.agents/plugins/marketplace.json` is the personal marketplace and needs no explicit add. Repo and team marketplaces are opt-in. Remote sources install under `$CODEX_HOME/.tmp/marketplaces/<name>/` and are recorded in `config.toml` under `[marketplaces.<name>]` with `source_type`, `source`, `ref`, and `sparse`.
+
+CLI: `codex plugin marketplace add <source>` / `list` / `upgrade` / `remove`; `codex plugin add PLUGIN@MARKETPLACE` / `list` / `remove`. The `add` grammar accepts `owner/repo`, any git URL, an SSH URL, or a local directory; `--ref` and `--sparse` are git-only; a file is rejected.
+
+## Marketplace fields
+
+Top level: `name` (required, `[A-Za-z0-9_-]+`), `plugins` (required, ordered = render order), `interface.displayName` (optional).
+
+Entry: `name` (required; must match the folder and manifest name), `source` (required), `category`, `policy`, plus any plugin-manifest field inlined as a flattened fallback.
+
+`policy`: `installation` (`NOT_AVAILABLE` \| `AVAILABLE` \| `INSTALLED_BY_DEFAULT`, default `AVAILABLE`), `authentication` (`ON_INSTALL` \| `ON_USE`, default `ON_INSTALL`), `products` (empty array denies every product).
+
+Sources — a bare string is a local relative path:
+
+| Form         | Shape                                                                        |
+| ------------ | ---------------------------------------------------------------------------- |
+| `local`      | `{source, path}`                                                             |
+| `url`        | `{source, url, path?, ref?, sha?}`                                           |
+| `git-subdir` | `{source, url, path, ref?, sha?}`                                            |
+| `npm`        | `{source, package, version?, registry?}`                                     |
+| `github`     | **Not supported** — the tagged enum has only Local, Url, GitSubdir, and Npm. |
+
+GitHub shorthand `owner/repo` is normalized to `https://github.com/owner/repo.git` inside `url`/`git-subdir`.
+
+## Directory layout
+
+```text
+<plugin-root>/
+├── .codex-plugin/plugin.json          # manifest (or overlay)
+├── .codex-plugin/migrated-command-skills/
+├── skills/<name>/SKILL.md
+├── hooks/
+├── scripts/
+├── assets/                            # composerIcon, logo, logoDark, screenshots
+├── .mcp.json
+└── .app.json
+```
+
+Codex has no LSP field and no LSP component location.
+
+## Evidence gaps
+
+1. OpenAI's prose documentation is not machine-readable, so no prose doc was quoted.
+2. The runtime/validator disagreement on `hooks` and `commands` has no documented resolution.
+3. No published schema exists for the legacy manifest or the marketplace manifest; `validate_plugin.py` claims to mirror an internal ingestion schema that is not public.

package/schemas/cursor/marketplace.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/cursor/marketplace.schema.json",
+  "title": "Cursor Marketplace Manifest",
+  "description": "Marketplace catalog read by Cursor at .cursor-plugin/marketplace.json in the repository root. Authored from the official Cursor plugin reference and the official plugin template; Cursor publishes no JSON Schema.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Sources: https://cursor.com/docs/reference/plugins ; cursor/plugin-template/.cursor-plugin/marketplace.json ; real catalogs (tldraw/tldraw for metadata.pluginRoot, cloudflare/skills, huggingface/skills, NVIDIA/skills, wshobson/agents). The docs describe the entry source object only as \"object with path and options\" and leave the option set unspecified, so it is modeled as an object requiring path. When a per-plugin manifest exists, it is merged with the entry and manifest values take precedence.",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string", "description": "Marketplace identifier (kebab-case)." },
+    "owner": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "url": { "type": "string", "description": "Used in real catalogs; not in the docs field table." }
+      },
+      "required": ["name"],
+      "additionalProperties": true
+    },
+    "plugins": { "type": "array", "maxItems": 500, "items": { "$ref": "#/$defs/entry" }, "description": "Plugin entries; at most 500." },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "description": { "type": "string" },
+        "version": { "type": "string" },
+        "pluginRoot": { "type": "string", "description": "Prefix path for all plugin sources; a bare source name resolves under it." }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["name", "owner", "plugins"],
+  "additionalProperties": true,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "description": "Kebab-case plugin name." },
+        "source": { "$ref": "#/$defs/source" },
+        "description": { "type": "string" },
+        "version": { "type": "string" },
+        "displayName": { "type": "string" },
+        "author": {
+          "type": "object",
+          "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "url": { "type": "string" } },
+          "required": ["name"],
+          "additionalProperties": true
+        },
+        "homepage": { "type": "string" },
+        "repository": { "type": "string" },
+        "license": { "type": "string" },
+        "keywords": { "type": "array", "items": { "type": "string" } },
+        "logo": { "type": "string" },
+        "category": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "skills": { "$ref": "#/$defs/pathList" },
+        "rules": { "$ref": "#/$defs/pathList" },
+        "agents": { "$ref": "#/$defs/pathList" },
+        "commands": { "$ref": "#/$defs/pathList" },
+        "hooks": { "anyOf": [{ "type": "string" }, { "type": "object" }] },
+        "mcpServers": { "anyOf": [{ "type": "string" }, { "type": "object" }] },
+        "variables": { "type": "object", "description": "Variable schema; prefer the plugin manifest, whose values win when both are set." }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": true
+    },
+    "source": {
+      "description": "Path to the plugin directory, or an object with path and options. Resolution: look for <source>/.cursor-plugin/plugin.json, merge it with this entry (manifest wins), then run component discovery inside the source directory.",
+      "anyOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "properties": { "path": { "type": "string" } },
+          "required": ["path"],
+          "additionalProperties": true
+        }
+      ]
+    },
+    "pathList": {
+      "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    }
+  }
+}

package/schemas/cursor/plugin.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/cursor/plugin.schema.json",
+  "title": "Cursor Plugin Manifest",
+  "description": "Cursor Plugin manifest at .cursor-plugin/plugin.json. Cursor also loads the agent-plugins.org format from a root plugin.json, which the vendored schemas/1.0.0/plugin.schema.json covers. Authored from the official Cursor plugin reference and the official plugin template; Cursor publishes no JSON Schema.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Sources: https://cursor.com/docs/reference/plugins ; cursor/plugin-template (.cursor-plugin/plugin.json) ; vercel/vercel-plugin. displayName and author.url are used by the official template and multiple vendor repos but are absent from the docs field table. Cursor documents no lspServers, outputStyles, workflows, userConfig, settings, strict, or dependencies for this manifest. A manifest field replaces folder discovery for that component; a root SKILL.md with no skills/ directory and no skills field loads as a single-skill plugin.",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string", "description": "Lowercase kebab-case identifier (alphanumerics, hyphens, periods); must start and end with an alphanumeric character." },
+    "displayName": { "type": "string", "description": "UI label. Present in the official template and vendor manifests; missing from the docs field table." },
+    "description": { "type": "string" },
+    "version": { "type": "string", "description": "Semantic version." },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "url": { "type": "string", "description": "Used in the wild; not in the docs field table." }
+      },
+      "required": ["name"],
+      "additionalProperties": true
+    },
+    "homepage": { "type": "string" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "logo": { "type": "string", "description": "Relative repository path resolved to raw.githubusercontent.com, or an absolute URL; relative is preferred." },
+    "rules": { "$ref": "#/$defs/pathList", "description": "Rule files or directories (.md, .mdc, .markdown). Default rules/." },
+    "agents": { "$ref": "#/$defs/pathList", "description": "Agent files or directories. Default agents/." },
+    "skills": { "$ref": "#/$defs/pathList", "description": "Skill directories. Default skills/." },
+    "commands": { "$ref": "#/$defs/pathList", "description": "Command files or directories (.md, .mdc, .markdown, .txt). Default commands/." },
+    "hooks": {
+      "description": "Path to a hooks configuration file or an inline hook configuration. Default hooks/hooks.json.",
+      "anyOf": [{ "type": "string" }, { "type": "object" }]
+    },
+    "mcpServers": {
+      "description": "Path, inline server map, or array of either. Overrides default mcp.json discovery.",
+      "anyOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }]
+    },
+    "variables": {
+      "type": "object",
+      "description": "JSON Schema declaring variable names only (never secret values). ${VAR} placeholders are substituted into mcp.json and similar files; values are configured by admins in the dashboard.",
+      "properties": {
+        "type": { "const": "object" },
+        "properties": { "type": "object" },
+        "required": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": true,
+  "$defs": {
+    "pathList": {
+      "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    }
+  }
+}

package/schemas/cursor/spec.md

@@ -0,0 +1,92 @@
+# Cursor plugin and marketplace specification
+
+Reference contract for Cursor plugin repositories. Machine-readable companions: [plugin.schema.json](plugin.schema.json) and [marketplace.schema.json](marketplace.schema.json).
+
+- **Verified:** 2026-09-08.
+- **Evidence:** official reference pages [`cursor.com/docs/reference/plugins`](https://cursor.com/docs/reference/plugins) and [`cursor.com/docs/plugins`](https://cursor.com/docs/plugins); the official [`cursor/plugin-template`](https://github.com/cursor/plugin-template); real catalogs (`tldraw/tldraw`, `cloudflare/skills`, `huggingface/skills`, `NVIDIA/skills`, `wshobson/agents`, `vercel/vercel-plugin`).
+- **Upstream JSON Schema:** none for `.cursor-plugin/plugin.json` or `.cursor-plugin/marketplace.json` (probed URLs return the SPA HTML). The agent-plugins.org schemas Cursor consumes are published upstream.
+
+## Two accepted formats
+
+Cursor loads a format by manifest location:
+
+| Format                        | Manifest                     | Components                                                                                   |
+| ----------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------- |
+| Agent Plugins (open standard) | root `plugin.json`           | Skills and MCP only; validated by [../1.0.0/plugin.schema.json](../1.0.0/plugin.schema.json) |
+| Cursor Plugin                 | `.cursor-plugin/plugin.json` | Skills, MCP, rules, agents, commands, hooks, variables                                       |
+
+Which format wins when both manifests exist is undocumented.
+
+## Plugin manifest (`.cursor-plugin/plugin.json`)
+
+Required: `name` — lowercase kebab-case with optional periods, starting and ending alphanumeric.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `name` | string | — | Plugin identifier. |
+| `displayName` | string | — | Used by the official template and vendor repos; missing from the docs field table. |
+| `description`, `version`, `homepage`, `repository`, `license` | string | — |  |
+| `author` | `{name, email?, url?}` | — | `url` is used in the wild but absent from the docs table. |
+| `keywords` | string[] | — |  |
+| `logo` | string | — | Relative repository path (resolved to `raw.githubusercontent.com`) or absolute URL; relative is preferred. |
+| `rules` | string \| string[] | `rules/` | `.md`, `.mdc`, `.markdown`. |
+| `agents` | string \| string[] | `agents/` |  |
+| `skills` | string \| string[] | `skills/` |  |
+| `commands` | string \| string[] | `commands/` | `.md`, `.mdc`, `.markdown`, `.txt`. |
+| `hooks` | string \| object | `hooks/hooks.json` |  |
+| `mcpServers` | string \| object \| string[] \| object[] | `mcp.json` | A manifest value overrides default discovery. |
+| `variables` | object | — | JSON Schema declaring variable **names** only. `${VAR}` placeholders are substituted into `mcp.json`; values are set by admins in the dashboard. |
+
+`variables` must be `{"type": "object", "properties": {...}}` and accepts only `type`, `title`, `description`, `default`, `enum`, `const`, `properties`, `required`, `items`, and common length/numeric constraints.
+
+Cursor documents no `lspServers`, `outputStyles`, `workflows`, `userConfig`, `settings`, `strict`, or `dependencies` for this manifest. A manifest field replaces folder discovery for that component.
+
+## Marketplace manifest (`.cursor-plugin/marketplace.json`)
+
+Required: `name`, `owner`, `plugins` (max 500 entries).
+
+| Field      | Type                                    | Notes                                                   |
+| ---------- | --------------------------------------- | ------------------------------------------------------- |
+| `name`     | string                                  | Marketplace identifier.                                 |
+| `owner`    | `{name, email?}`                        | Real catalogs also use `url`.                           |
+| `plugins`  | array                                   | At most 500 entries.                                    |
+| `metadata` | `{description?, version?, pluginRoot?}` | `pluginRoot` is the prefix path for all plugin sources. |
+
+Entry fields: `name` (required), `source` (required), `description`, `version`, `author`, `homepage`, `repository`, `license`, `keywords`, `logo`, `category`, `tags`, `skills`, `rules`, `agents`, `commands`, `hooks`, `mcpServers`, `variables`.
+
+`source` is "a path to the plugin directory, or an object with `path` and options" — the docs leave the option set unspecified. Resolution: look for `<source>/.cursor-plugin/plugin.json`, merge it with the entry (**manifest values take precedence**), then discover components inside the source directory using manifest paths where declared.
+
+A bare source name resolves under `metadata.pluginRoot` (for example `tldraw/tldraw`: `pluginRoot: "apps/mcp-app/plugins"`, `source: "tldraw-mcp"`).
+
+## Directory layout
+
+```text
+my-plugin/
+├── .cursor-plugin/plugin.json   # required manifest
+├── rules/                       # .mdc files
+├── skills/<name>/SKILL.md
+├── agents/
+├── commands/
+├── hooks/hooks.json
+├── mcp.json                     # documented default; the dot-file .mcp.json is not auto-discovered
+├── assets/
+└── scripts/
+```
+
+Hook events include `sessionStart`, `sessionEnd`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `subagentStart`, `subagentStop`, `beforeShellExecution`, `afterShellExecution`, `beforeMCPExecution`, `afterMCPExecution`, `beforeReadFile`, `afterFileEdit`, `beforeSubmitPrompt`, `preCompact`, `stop`, `afterAgentResponse`, `afterAgentThought`, `beforeTabFileRead`, `afterTabFileEdit`, and `workspaceOpen`; entries carry `command` and `matcher`.
+
+## Precedence
+
+1. Marketplace entry versus plugin manifest: manifest values win.
+2. Component path versus discovery: a declared field replaces discovery for that component.
+3. MCP: a manifest `mcpServers` value overrides `mcp.json` discovery.
+4. Local development: `~/.cursor/plugins/local/<name>` loses to an installed marketplace plugin of the same name.
+
+## Evidence gaps
+
+1. `displayName` and `author.url` are used by official repos but missing from the docs table.
+2. The marketplace entry `source` object's option set is unspecified.
+3. Hook merge precedence (inline versus file, plugin versus project) is undocumented.
+4. Format precedence when both a root `plugin.json` and `.cursor-plugin/plugin.json` exist is undocumented.
+5. Whether Cursor auto-discovers `.mcp.json` (dot) is unverified; the documented default is `mcp.json`.
+6. No LSP support is documented for Cursor plugins.

package/schemas/github-copilot/marketplace.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/github-copilot/marketplace.schema.json",
+  "title": "GitHub Copilot CLI Marketplace Manifest",
+  "description": "Marketplace catalog read by GitHub Copilot CLI, looked up as marketplace.json, .plugin/marketplace.json, .github/plugin/marketplace.json, then .claude-plugin/marketplace.json. Authored from the official CLI plugin reference; GitHub publishes no JSON Schema for this manifest.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Source: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference (raw markdown in github/docs). Marketplace names must be kebab-case (dots accepted for Open Plugin Spec plugins) and max 64 chars; the marketplace's own name becomes its registration key.",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string", "maxLength": 64, "description": "Kebab-case marketplace name; dots are also accepted for Open Plugin Spec plugins." },
+    "owner": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" }
+      },
+      "required": ["name"],
+      "additionalProperties": true
+    },
+    "plugins": { "type": "array", "items": { "$ref": "#/$defs/entry" } },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "description": { "type": "string" },
+        "version": { "type": "string" },
+        "pluginRoot": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["name", "owner", "plugins"],
+  "additionalProperties": true,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "maxLength": 64, "description": "Kebab-case plugin name; dots are also accepted for Open Plugin Spec plugins." },
+        "source": { "$ref": "#/$defs/source" },
+        "description": { "type": "string", "maxLength": 1024 },
+        "version": { "type": "string" },
+        "author": {
+          "type": "object",
+          "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "url": { "type": "string" } },
+          "required": ["name"],
+          "additionalProperties": true
+        },
+        "homepage": { "type": "string" },
+        "repository": { "type": "string" },
+        "license": { "type": "string" },
+        "keywords": { "type": "array", "items": { "type": "string" } },
+        "category": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "commands": { "$ref": "#/$defs/pathList" },
+        "agents": { "$ref": "#/$defs/pathList" },
+        "skills": { "$ref": "#/$defs/pathList" },
+        "hooks": { "anyOf": [{ "type": "string" }, { "type": "object" }] },
+        "mcpServers": {
+          "description": "MCP servers to activate when the plugin is installed; an inline server map or a path to a JSON configuration file. Used when the plugin source does not ship its own MCP configuration.",
+          "anyOf": [{ "type": "string" }, { "type": "object" }]
+        },
+        "lspServers": {
+          "description": "Path to LSP configuration or inline server definitions.",
+          "anyOf": [{ "type": "string" }, { "type": "object" }]
+        },
+        "strict": {
+          "type": "boolean",
+          "default": true,
+          "description": "When true (the default) plugins must conform to the full schema and validation rules; false enables relaxed validation for direct installs or legacy plugins."
+        }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": true
+    },
+    "source": {
+      "description": "A relative path string, or an object describing a GitHub repository or Git URL source.",
+      "anyOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "github" },
+            "repo": { "type": "string" },
+            "ref": { "type": "string" },
+            "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$", "description": "Full 40-character commit SHA; pins installs against force-pushes and moved tags." },
+            "path": { "type": "string" }
+          },
+          "required": ["source", "repo"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "url" },
+            "url": { "type": "string" },
+            "ref": { "type": "string" },
+            "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+            "path": { "type": "string" }
+          },
+          "required": ["source", "url"],
+          "additionalProperties": true
+        }
+      ]
+    },
+    "pathList": {
+      "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    }
+  }
+}

package/schemas/github-copilot/plugin.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/github-copilot/plugin.schema.json",
+  "title": "GitHub Copilot CLI Plugin Manifest",
+  "description": "Plugin manifest accepted by GitHub Copilot CLI, looked up as .plugin/plugin.json, plugin.json, .github/plugin/plugin.json, then .claude-plugin/plugin.json. Authored from the official CLI plugin reference; GitHub publishes no JSON Schema for this manifest.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Source: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference (raw markdown in github/docs). Declaring the canonical agent-plugins.org $schema opts the plugin into Agent Plugins v1.0.0 additively; the extensions field then changes meaning. Unknown properties are reported and ignored.",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string", "description": "Set to the agent-plugins.org v1.0.0 plugin schema URL to opt into Open Plugin Spec semantics." },
+    "name": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "Kebab-case plugin name (letters, numbers, hyphens). Plugins opting into Open Plugin Spec support may also use dots, for example acme.tools."
+    },
+    "description": { "type": "string", "maxLength": 1024 },
+    "version": { "type": "string", "description": "Semantic version, e.g. 1.0.0." },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "url": { "type": "string" }
+      },
+      "required": ["name"],
+      "additionalProperties": true
+    },
+    "homepage": { "type": "string" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "category": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "agents": { "$ref": "#/$defs/pathList", "description": "Path(s) to agent directories containing .agent.md files. Default agents/." },
+    "skills": { "$ref": "#/$defs/pathList", "description": "Path(s) to skill directories containing SKILL.md. Default skills/." },
+    "commands": { "$ref": "#/$defs/pathList", "description": "Path(s) to command directories." },
+    "hooks": {
+      "description": "Path to a hooks configuration file, or an inline hooks object.",
+      "anyOf": [{ "type": "string" }, { "type": "object" }]
+    },
+    "extensions": {
+      "description": "Path(s) to extension directories, or { paths: [...], exclusive: true } to suppress built-in extensions. In Open Plugin Spec mode the field has a different meaning.",
+      "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object" }]
+    },
+    "mcpServers": {
+      "description": "Path to an MCP configuration file such as .mcp.json, or inline server definitions.",
+      "anyOf": [{ "type": "string" }, { "type": "object" }]
+    },
+    "lspServers": {
+      "description": "Path to an LSP configuration file, or inline server definitions.",
+      "anyOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "properties": { "lspServers": { "type": "object", "additionalProperties": { "$ref": "#/$defs/lspServer" } } },
+          "additionalProperties": true
+        }
+      ]
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": true,
+  "$defs": {
+    "pathList": {
+      "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    },
+    "lspServer": {
+      "type": "object",
+      "description": "One language server. At least one of command, bash, or powershell is required. When both bash and powershell are given, the platform-appropriate one is selected automatically.",
+      "properties": {
+        "command": { "type": "string", "description": "Executable to launch the server." },
+        "bash": { "type": "string", "description": "Bash script for Linux/macOS, executed via bash -c SCRIPT." },
+        "powershell": { "type": "string", "description": "PowerShell script for Windows, executed via pwsh -c SCRIPT." },
+        "cwd": { "type": "string", "description": "Working directory; absolute or relative to the configuration file. Supports ${PLUGIN_ROOT}." },
+        "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments for command; ignored for bash and powershell." },
+        "env": { "type": "object", "additionalProperties": { "type": "string" } },
+        "fileExtensions": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Map of file extension to language id, for example { \".ts\": \"typescript\" }."
+        },
+        "rootUri": { "type": "string", "description": "Project root relative to the git root; default \".\"." },
+        "initializationOptions": { "description": "Options sent in the LSP initialize request." }
+      },
+      "required": ["fileExtensions"],
+      "anyOf": [{ "required": ["command"] }, { "required": ["bash"] }, { "required": ["powershell"] }],
+      "additionalProperties": true
+    }
+  }
+}