universal-plugin 0.5.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/dist/cli.mjs

@@ -423,9 +423,26 @@ const COMMON_METADATA = [
 function assertMarketplaceName(value, label) {
 	if (!/^[a-z0-9][a-z0-9._-]*$/i.test(value)) throw new Error(`error: ${label} "${value}" must contain only letters, digits, dots, underscores, or hyphens`);
 }
+/** A manifest field carried into a catalog entry, in the shape the catalog schema states. A manifest
+*  written from a `package.json` carries `repository` as `{ type, url }`, and every catalog wants the
+*  URL alone — Claude Code rejects the object (`plugins[].repository: expected string`). A value that
+*  cannot be reduced to the right type is dropped rather than written: an entry missing an optional
+*  field still installs, an entry with the wrong type installs nowhere. */
+function catalogValue(field, value) {
+	if (field === "keywords") return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+	if (field === "repository" && typeof value === "object" && value !== null && !Array.isArray(value)) {
+		const url = value.url;
+		return typeof url === "string" ? url.replace(/^git\+/, "") : void 0;
+	}
+	return typeof value === "string" ? value : void 0;
+}
 function commonMetadata(plugin) {
 	const result = {};
-	for (const field of COMMON_METADATA) if (plugin.metadata[field] !== void 0) result[field] = plugin.metadata[field];
+	for (const field of COMMON_METADATA) {
+		if (plugin.metadata[field] === void 0) continue;
+		const value = catalogValue(field, plugin.metadata[field]);
+		if (value !== void 0) result[field] = value;
+	}
 	return result;
 }
 function json(value) {
@@ -665,6 +682,235 @@ function gatherCatalogRepo(root) {
 	};
 }
 //#endregion
+//#region src/marketplace/validation.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function checkString(issues, path, value, { required = false } = {}) {
+	if (value === void 0) {
+		if (required) issues.push({
+			path,
+			message: "is required"
+		});
+		return;
+	}
+	if (typeof value !== "string") {
+		issues.push({
+			path,
+			message: `must be a string, not ${typeName(value)}`
+		});
+		return;
+	}
+	if (required && value.trim() === "") issues.push({
+		path,
+		message: "must not be empty"
+	});
+}
+function checkStringArray(issues, path, value) {
+	if (value === void 0) return;
+	if (!Array.isArray(value)) {
+		issues.push({
+			path,
+			message: `must be an array of strings, not ${typeName(value)}`
+		});
+		return;
+	}
+	value.forEach((item, index) => {
+		checkString(issues, `${path}[${index}]`, item);
+	});
+}
+/** `owner` and a plugin's `author` share one shape: an object carrying a required `name`. A string
+*  there is the mistake `package.json`'s `"author": "Name <email>"` invites; Claude Code reports
+*  `expected object, received string` and refuses the catalog. */
+function checkPerson(issues, path, value, { required = false } = {}) {
+	if (value === void 0) {
+		if (required) issues.push({
+			path,
+			message: "is required"
+		});
+		return;
+	}
+	if (!isObject(value)) {
+		const remedy = typeof value === "string" ? ` — write { "name": ${JSON.stringify(value)} }` : "";
+		issues.push({
+			path,
+			message: `must be an object with a name, not ${typeName(value)}${remedy}`
+		});
+		return;
+	}
+	checkString(issues, `${path}.name`, value.name, { required: true });
+	checkString(issues, `${path}.email`, value.email);
+	checkString(issues, `${path}.url`, value.url);
+}
+/** The source forms the official schema accepts: a `./`-prefixed repository-relative path, or one of
+*  the tagged remote objects. */
+const REMOTE_SOURCE_KEYS = {
+	npm: ["package"],
+	url: ["url"],
+	github: ["repo"],
+	"git-subdir": ["url", "path"]
+};
+function checkClaudeSource(issues, path, value) {
+	if (value === void 0) {
+		issues.push({
+			path,
+			message: "is required"
+		});
+		return;
+	}
+	if (typeof value === "string") {
+		if (!value.startsWith("./")) issues.push({
+			path,
+			message: `must be a "./"-prefixed repository-relative path, not ${JSON.stringify(value)}`
+		});
+		return;
+	}
+	if (!isObject(value)) {
+		issues.push({
+			path,
+			message: `must be a "./" path or a source object, not ${typeName(value)}`
+		});
+		return;
+	}
+	const kind = value.source;
+	if (typeof kind !== "string" || !(kind in REMOTE_SOURCE_KEYS)) {
+		issues.push({
+			path: `${path}.source`,
+			message: `must be one of ${Object.keys(REMOTE_SOURCE_KEYS).join(", ")}`
+		});
+		return;
+	}
+	for (const key of REMOTE_SOURCE_KEYS[kind]) checkString(issues, `${path}.${key}`, value[key], { required: true });
+}
+function checkClaudeEntry(issues, path, entry) {
+	if (!isObject(entry)) {
+		issues.push({
+			path,
+			message: `must be an object, not ${typeName(entry)}`
+		});
+		return;
+	}
+	checkString(issues, `${path}.name`, entry.name, { required: true });
+	checkClaudeSource(issues, `${path}.source`, entry.source);
+	checkString(issues, `${path}.version`, entry.version);
+	checkString(issues, `${path}.description`, entry.description);
+	checkString(issues, `${path}.homepage`, entry.homepage);
+	if (isObject(entry.repository) && typeof entry.repository.url === "string") issues.push({
+		path: `${path}.repository`,
+		message: `must be a string, not object — write ${JSON.stringify(entry.repository.url)}`
+	});
+	else checkString(issues, `${path}.repository`, entry.repository);
+	checkString(issues, `${path}.license`, entry.license);
+	checkString(issues, `${path}.category`, entry.category);
+	checkPerson(issues, `${path}.author`, entry.author);
+	checkStringArray(issues, `${path}.keywords`, entry.keywords);
+	checkStringArray(issues, `${path}.tags`, entry.tags);
+}
+function validateClaudeShaped(catalog) {
+	const issues = [];
+	checkString(issues, "name", catalog.name, { required: true });
+	checkPerson(issues, "owner", catalog.owner, { required: true });
+	checkString(issues, "description", catalog.description);
+	checkString(issues, "version", catalog.version);
+	if (catalog.plugins === void 0) {
+		issues.push({
+			path: "plugins",
+			message: "is required"
+		});
+		return issues;
+	}
+	if (!Array.isArray(catalog.plugins)) {
+		issues.push({
+			path: "plugins",
+			message: `must be an array, not ${typeName(catalog.plugins)}`
+		});
+		return issues;
+	}
+	catalog.plugins.forEach((entry, index) => {
+		checkClaudeEntry(issues, `plugins[${index}]`, entry);
+	});
+	return issues;
+}
+/** Codex reads a document of its own: no `owner`, a display name under `interface`, and an object
+*  `source` naming a local path (`.research/local-marketplaces`, E-CODEX-M11). It tolerates extra
+*  keys and requires no entry `version`. */
+function validateCodex(catalog) {
+	const issues = [];
+	checkString(issues, "name", catalog.name, { required: true });
+	if (catalog.interface !== void 0 && !isObject(catalog.interface)) issues.push({
+		path: "interface",
+		message: `must be an object, not ${typeName(catalog.interface)}`
+	});
+	else if (isObject(catalog.interface)) checkString(issues, "interface.displayName", catalog.interface.displayName);
+	if (catalog.plugins === void 0) {
+		issues.push({
+			path: "plugins",
+			message: "is required"
+		});
+		return issues;
+	}
+	if (!Array.isArray(catalog.plugins)) {
+		issues.push({
+			path: "plugins",
+			message: `must be an array, not ${typeName(catalog.plugins)}`
+		});
+		return issues;
+	}
+	catalog.plugins.forEach((entry, index) => {
+		const path = `plugins[${index}]`;
+		if (!isObject(entry)) {
+			issues.push({
+				path,
+				message: `must be an object, not ${typeName(entry)}`
+			});
+			return;
+		}
+		checkString(issues, `${path}.name`, entry.name, { required: true });
+		checkString(issues, `${path}.version`, entry.version);
+		checkString(issues, `${path}.category`, entry.category);
+		if (typeof entry.source === "string") checkClaudeSource(issues, `${path}.source`, entry.source);
+		else if (isObject(entry.source)) {
+			checkString(issues, `${path}.source.source`, entry.source.source, { required: true });
+			if (entry.source.source === "local") checkClaudeSource(issues, `${path}.source.path`, entry.source.path);
+		} else issues.push({
+			path: `${path}.source`,
+			message: "is required"
+		});
+	});
+	return issues;
+}
+/** Every issue a target's runtime would raise against this catalog, empty when it loads. */
+function validateCatalog(target, catalog) {
+	if (!isObject(catalog)) return [{
+		path: "",
+		message: `catalog must be a JSON object, not ${typeName(catalog)}`
+	}];
+	return target === "codex" ? validateCodex(catalog) : validateClaudeShaped(catalog);
+}
+/** The same check against a catalog still in its serialized form. Text that does not parse is one
+*  issue rather than a thrown error, so a caller checking four files reports all four. */
+function validateCatalogContent(target, content) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch (err) {
+		return [{
+			path: "",
+			message: `is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+		}];
+	}
+	return validateCatalog(target, parsed);
+}
+/** One error message naming the file and every issue in it, for a caller that fails loud. */
+function formatCatalogIssues(file, issues) {
+	return `error: catalog "${file}" does not match the marketplace schema:\n${issues.map((issue) => `  ${issue.path === "" ? file : `${issue.path}`} ${issue.message}`).join("\n")}`;
+}
+//#endregion
 //#region src/build/build.ts
 /** Where each vendor reads its manifest, relative to the project root. Shared with
 *  `plugin init --npm`, which wires exactly these paths into `package.json` `files`. */
@@ -848,6 +1094,8 @@ function refreshCatalogs(root, manifest, vendors, opts, written, warnings) {
 		if (existing === void 0) continue;
 		try {
 			const artifact = refreshCatalogEntry(target, plugin, existing);
+			const issues = validateCatalogContent(target, artifact.content);
+			if (issues.length > 0) warnings.push(formatCatalogIssues(relative, issues));
 			if (sameCatalogContent(artifact.content, existing)) {
 				rows.push({
 					path: relative,
@@ -1775,6 +2023,8 @@ function planCatalogs(state, opts, manifest, notes) {
 		const target = VENDOR_TARGETS[vendor];
 		if (!target) continue;
 		const artifact = mergeCatalogEntry(target, metadata, plugin, (path) => repo.catalogs[path]);
+		const issues = validateCatalogContent(target, artifact.content);
+		if (issues.length > 0) notes.push(formatCatalogIssues(artifact.path, issues));
 		catalogs.push({
 			path: `${toPluginRoot}${artifact.path}`,
 			content: artifact.content
@@ -2378,7 +2628,11 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 		target,
 		artifacts: serializeTarget(target, metadata, plugins)
 	}));
-	for (const { artifacts } of planned) for (const artifact of artifacts) assertContained(root, path.join(root, artifact.path), fs, "selected artifact");
+	for (const { target, artifacts } of planned) for (const artifact of artifacts) {
+		assertContained(root, path.join(root, artifact.path), fs, "selected artifact");
+		const issues = validateCatalogContent(target, artifact.content);
+		if (issues.length > 0) throw new Error(formatCatalogIssues(artifact.path, issues));
+	}
 	const conflicts = [];
 	for (const entry of planned) for (const artifact of entry.artifacts) {
 		const output = path.join(root, artifact.path);
@@ -2405,6 +2659,66 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 	return results;
 }
 //#endregion
+//#region src/marketplace/validate.ts
+/** A `./`-prefixed source names a directory inside the repository, and Claude Code resolves it
+*  against the directory holding `.claude-plugin/`. A source pointing nowhere passes every schema
+*  check and still installs nothing, so the on-disk check belongs here rather than in the rules. */
+function checkSources(root, fs, catalog) {
+	if (typeof catalog !== "object" || catalog === null) return [];
+	const plugins = catalog.plugins;
+	if (!Array.isArray(plugins)) return [];
+	const issues = [];
+	plugins.forEach((entry, index) => {
+		if (typeof entry !== "object" || entry === null) return;
+		const source = entry.source;
+		const location = typeof source === "string" ? source : typeof source === "object" && source !== null ? source.path : void 0;
+		if (typeof location !== "string" || !location.startsWith("./")) return;
+		if (!fs.exists(path.join(root, location))) issues.push({
+			path: `plugins[${index}].source`,
+			message: `points at "${location}", which does not exist`
+		});
+	});
+	return issues;
+}
+/** Checks the catalogs a repository carries against the shape each runtime loads. Reads only; it
+*  repairs nothing, because a catalog someone hand-edited is theirs to correct. */
+function validateMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
+	const root = path.resolve(rootInput);
+	return (opts.targets && opts.targets.length > 0 ? [...new Set(opts.targets)] : [
+		"claude",
+		"codex",
+		"copilot",
+		"cursor"
+	]).map((target) => {
+		const relative = TARGET_CATALOG_PATHS[target];
+		const file = path.join(root, relative);
+		if (!fs.exists(file)) return {
+			target,
+			path: relative,
+			status: opts.required ? "invalid" : "missing",
+			issues: opts.required ? [{
+				path: "",
+				message: "no catalog at this path"
+			}] : []
+		};
+		const content = fs.read(file);
+		const issues = [...validateCatalogContent(target, content), ...parseAndCheckSources(root, fs, content)];
+		return {
+			target,
+			path: relative,
+			status: issues.length === 0 ? "valid" : "invalid",
+			issues
+		};
+	});
+}
+function parseAndCheckSources(root, fs, content) {
+	try {
+		return checkSources(root, fs, JSON.parse(content));
+	} catch {
+		return [];
+	}
+}
+//#endregion
 //#region src/marketplace/cli.ts
 function targetsFromOptions(opts) {
 	const targets = [
@@ -2443,8 +2757,36 @@ function initCommand() {
 		}
 	});
 }
+function validateCommand() {
+	return new Command("validate").description("Check the repository-local marketplace catalogs against the schema each runtime loads").option("--claude", "Validate the Claude marketplace catalog").option("--codex", "Validate the Codex marketplace catalog").option("--copilot", "Validate the Copilot marketplace catalog").option("--cursor", "Validate the Cursor marketplace catalog").option("--required", "Treat a selected target with no catalog as a failure").option("--format <format>", "Output format: toon or json (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin marketplace validate --claude\n").action((opts) => {
+		try {
+			if (opts.format !== void 0 && opts.format !== "toon" && opts.format !== "json") throw new Error("error: --format must be \"toon\" or \"json\"");
+			const results = validateMarketplace(resolveRoot(opts.root), {
+				targets: targetsFromOptions(opts),
+				required: opts.required
+			});
+			output(results, {
+				targets: results.map((row) => ({
+					target: row.target,
+					status: row.status,
+					path: row.path,
+					issues: row.issues.length
+				})),
+				summary: `${results.filter((row) => row.status === "invalid").length} invalid of ${results.length}`
+			});
+			for (const row of results.filter((row) => row.status === "invalid")) {
+				process.stderr.write(formatCatalogIssues(row.path, row.issues));
+				process.stderr.write("\n");
+			}
+			if (results.some((row) => row.status === "invalid")) process.exitCode = 1;
+		} catch (err) {
+			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+			process.exitCode = 1;
+		}
+	});
+}
 function marketplaceCommand() {
-	return new Command("marketplace").description("Generate repository-local marketplace metadata").addCommand(initCommand());
+	return new Command("marketplace").description("Generate repository-local marketplace metadata").addCommand(initCommand()).addCommand(validateCommand());
 }
 //#endregion
 //#region src/prepare/fs.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -44,6 +44,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/semver": "^7.7.1",
+    "ajv": "^8.20.0",
     "knip": "^6.14.1",
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -79,8 +79,12 @@ keep their previous version.
 
 ```sh
 npx universal-plugin marketplace init --codex --root .
+npx universal-plugin marketplace validate --root .
 ```
 
+`validate` checks each catalog against the schema its runtime loads and names the key at fault, so a
+catalog that would be refused at install time is caught in the repository.
+
 Codex caches a local plugin install by its marketplace entry version. After you change packaged
 plugin files: update the canonical `plugin.json` version, regenerate the catalog (add `--force` to
 replace an existing one), reinstall the plugin, then start a new Codex session. The installed copy

package/skills/doctor/README.md

@@ -8,7 +8,9 @@ disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
 `scripts/doctor.mjs` composes the shipped CLI's `plugin build --dry-run --format json` with the
 filesystem facts that build cannot see — whether each derived manifest exists, whether it predates
 the canonical manifest, whether a stale or shadowing manifest is lying around, whether the two
-authored version numbers still agree, and whether shipped content has moved since the version did. It emits one JSON object: `vendors`, `findings`, `ok`.
+authored version numbers still agree, whether shipped content has moved since the version did, and
+whether every marketplace catalog at the repository root is a shape its runtime loads. It emits one
+JSON object: `vendors`, `findings`, `ok`.
 
 The skill supplies the judgment around it: which finding matters, and which skill owns its repair.
 

package/skills/doctor/SKILL.md

@@ -76,6 +76,17 @@ Each `code` below is what the script emits.
 | `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin | `/universal-plugin:init`, update route |
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
 | `unparsable-manifest` | root `plugin.json` is not valid JSON | fix the syntax error |
+| `invalid-catalog` | a marketplace catalog at the repository root is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` |
+
+## Catalogs are checked at the repository root
+
+The marketplace catalogs sit above the plugin in a monorepo, so the catalog check runs against the
+repository root rather than `--root`. It reports only a catalog that would be **refused**: a missing
+one is not a fault, and nothing here has an opinion on which catalogs a repository ought to carry.
+
+The detail names the key at fault, so hand it to `/universal-plugin:marketplace` as it stands. An
+entry's fields are derived from the plugin's `plugin.json`, and the catalog's own `name` and `owner`
+are authored in the catalog — which half is at fault decides where the repair goes.
 
 ## Checking staleness properly
 

package/skills/doctor/scripts/doctor.mjs

@@ -199,8 +199,36 @@ if (manifest.version !== undefined && packagePath === null) {
 	}
 }
 
+// The marketplace catalogs a user installs from. They sit at the *repository* root, above a plugin in
+// a monorepo, and each is read by its runtime at install time — a catalog whose shape that runtime
+// refuses fails in the user's terminal, not here. The shipped CLI owns the rules; this only asks.
+for (const row of invalidCatalogs()) {
+	add(
+		'invalid-catalog',
+		'high',
+		`${row.path} is not a shape its runtime loads: ${row.issues.map((issue) => `${issue.path} ${issue.message}`).join('; ')}`,
+		'/universal-plugin:marketplace',
+	)
+}
+
 report({ vendors })
 
+/** Every catalog the repository carries that its runtime would refuse. Empty when there is nothing to
+ *  read, when the CLI is too old to answer, or when every catalog is fine — a missing catalog is not a
+ *  fault, and this reports no opinion on which ones a repository ought to carry. */
+function invalidCatalogs() {
+	const catalogRoot = git('rev-parse', '--show-toplevel') ?? root
+	const result = fs.existsSync(bin)
+		? spawnSync(process.execPath, [bin, 'marketplace', 'validate', '--format', 'json', '--root', catalogRoot], {
+				encoding: 'utf8',
+			})
+		: spawnSync('npx', ['universal-plugin', 'marketplace', 'validate', '--format', 'json', '--root', catalogRoot], {
+				encoding: 'utf8',
+			})
+	const rows = readJson_stdout(result.stdout)
+	return Array.isArray(rows) ? rows.filter((row) => row.status === 'invalid') : []
+}
+
 /** Runs git inside `root`, returning its stdout or `null` — a non-zero status, a missing git, and a
  *  directory outside any repository are all the same answer here: no history to read. */
 function git(...args) {

package/skills/marketplace/README.md

@@ -6,8 +6,8 @@ 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.
+runtime. This skill picks the targets with the user, runs the generation, validates every catalog
+against the schema its runtime loads, 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.
 
@@ -25,6 +25,16 @@ evidence ID. That constraint exists because the obvious way to write an install
 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 validation half
+
+`scripts/validate.mjs` checks each catalog against the shape its runtime actually loads and names the
+key at fault. It exists because a broken catalog fails silently here and loudly at install time, in
+someone else's terminal. Two shapes reach a repository unnoticed, both of them what `package.json`
+carries: `owner` as a `"Name <email>"` string, and `repository` as a `{ type, url }` object. Claude
+Code refuses the catalog for either. Generation now reduces what it can (an npm `repository` becomes
+its URL) and validation catches the rest, including a `./` source pointing at a directory that is not
+there.
+
 ## The README half
 
 `scripts/install-docs.mjs` reads the catalogs on disk and emits the section as JSON, so the
@@ -36,3 +46,5 @@ document.
 
 - [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)
+- [`marketplace validate` spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/marketplace/validate/README.md)
+- [Official Claude Code marketplace schema](https://json.schemastore.org/claude-code-marketplace.json)

package/skills/marketplace/SKILL.md

@@ -77,7 +77,43 @@ A selected artifact that differs from what would be generated stops the whole ru
 command protecting a hand-edited catalog. Read the difference, then re-run with `--force` only once
 you know what it discards.
 
-### 4. Offer the README section
+### 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.
+
+```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.
 
@@ -95,16 +131,12 @@ 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.
 
-### 5. Verify
+### 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.
 
-For Claude Code, check that each plugin `source` is a `./`-prefixed path that exists. 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.
-
 A local path is the cheapest end-to-end proof:
 
 ```bash
@@ -147,6 +179,11 @@ a version the plugin does not have.
 - **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
@@ -166,5 +203,7 @@ a version the plugin does not have.
 ## References
 
 - `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/scripts/validate.mjs

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