chore(plugin-dev): apply AI code review suggestions

- declare skills path in manifest so Codex exposes them (Greptile P1)
- rename skill names to lowercase-hyphen matching directories (cubic P1)
- correct $schema and Codex-marketplace-scope wording in reference (cubic P3)
- extract helpers so generateMultiFormat stays under the function-length guideline (Gemini)

Author: amondnet

plugins/plugin-dev/.claude-plugin/plugin.json

@@ -18,5 +18,8 @@
     "validation",
     "guidelines",
     "scaffold"
+  ],
+  "skills": [
+    "./skills/"
   ]
 }

plugins/plugin-dev/.codex-plugin/plugin.json

@@ -30,5 +30,6 @@
     "validation",
     "guidelines",
     "scaffold"
-  ]
+  ],
+  "skills": "./skills/"
 }

plugins/plugin-dev/scripts/run.ts

@@ -30,88 +30,101 @@ import {
 const ROOT = resolve(import.meta.dirname!, "..", "..", "..")
 const PLUGINS_DIR = join(ROOT, "plugins")
 
-/**
- * Generate Codex, Antigravity, and Cursor manifests for every local plugin so
- * the same plugin directory loads across runtimes.
- */
-export async function generateMultiFormat() {
+interface PluginRunResult {
+  pluginsProcessed: number
+  filesWritten: number
+  benignSkipped: string[]
+  failed: { name: string; error: string }[]
+}
+
+/** Read the Claude marketplace, or exit(1) if it is missing. */
+function loadMarketplace(): ClaudeMarketplace {
   const marketplaceJsonPath = join(ROOT, ".claude-plugin", "marketplace.json")
   if (!existsSync(marketplaceJsonPath)) {
     console.error(`! marketplace not found: ${marketplaceJsonPath}`)
     process.exit(1)
   }
+  return JSON.parse(readFileSync(marketplaceJsonPath, "utf-8")) as ClaudeMarketplace
+}
 
-  const marketplaceJson = JSON.parse(readFileSync(marketplaceJsonPath, "utf-8")) as ClaudeMarketplace
+/** Index local (`./plugins/...`) marketplace entries by their plugin directory name. */
+function localEntriesByDir(marketplaceJson: ClaudeMarketplace): Map<string, MarketplaceEntry> {
   const entriesByPluginDir = new Map<string, MarketplaceEntry>()
   for (const entry of marketplaceJson.plugins) {
     if (typeof entry.source === "string" && entry.source.startsWith("./plugins/")) {
-      const dirName = entry.source.replace(/^\.\/plugins\//, "")
-      entriesByPluginDir.set(dirName, entry)
+      entriesByPluginDir.set(entry.source.replace(/^\.\/plugins\//, ""), entry)
     }
   }
+  return entriesByPluginDir
+}
 
-  console.log("Generating Codex + Antigravity + Cursor manifests for local plugins...\n")
-  let pluginsProcessed = 0
-  let filesWritten = 0
-  const benignSkipped: string[] = []
-  const failed: { name: string; error: string }[] = []
+/** Generate per-runtime manifests for every plugin directory, logging per-plugin status. */
+function processPlugins(entriesByPluginDir: Map<string, MarketplaceEntry>): PluginRunResult {
+  const out: PluginRunResult = { pluginsProcessed: 0, filesWritten: 0, benignSkipped: [], failed: [] }
   const pluginDirs = readdirSync(PLUGINS_DIR, { withFileTypes: true })
     .filter(d => d.isDirectory())
     .map(d => d.name)
     .sort()
 
   for (const dirName of pluginDirs) {
-    const pluginDir = join(PLUGINS_DIR, dirName)
-    const entry = entriesByPluginDir.get(dirName)
     try {
-      const result = generateForPlugin(pluginDir, entry)
+      const result = generateForPlugin(join(PLUGINS_DIR, dirName), entriesByPluginDir.get(dirName))
       if (result.reason) {
         console.log(`  ${dirName}: skipped (${result.reason})`)
-        benignSkipped.push(dirName)
+        out.benignSkipped.push(dirName)
         continue
       }
-      pluginsProcessed++
+      out.pluginsProcessed++
       if (result.written.length === 0) {
         console.log(`  ${dirName}: up to date`)
       } else {
         console.log(`  ${dirName}: wrote ${result.written.length} file(s)`)
-        filesWritten += result.written.length
+        out.filesWritten += result.written.length
       }
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       console.error(`  ${dirName}: FAILED — ${msg}`)
-      failed.push({ name: dirName, error: msg })
+      out.failed.push({ name: dirName, error: msg })
     }
   }
+  return out
+}
 
-  // Generate Codex marketplace.json from the Claude one.
-  const codexMarketplace = toCodexMarketplace(marketplaceJson)
-  const codexMarketplacePath = join(ROOT, ".agents", "plugins", "marketplace.json")
-  const codexWritten = writeIfChanged(codexMarketplacePath, JSON.stringify(codexMarketplace, null, 2) + "\n")
+/** Emit the Codex + Cursor marketplace files from the Claude marketplace; returns files written. */
+function writeMarketplaces(marketplaceJson: ClaudeMarketplace): number {
+  const targets: { label: string; path: string; doc: unknown }[] = [
+    { label: "Codex", path: join(ROOT, ".agents", "plugins", "marketplace.json"), doc: toCodexMarketplace(marketplaceJson) },
+    { label: "Cursor", path: join(ROOT, ".cursor-plugin", "marketplace.json"), doc: toCursorMarketplace(marketplaceJson) },
+  ]
   console.log()
-  if (codexWritten) {
-    console.log(`Codex marketplace written: ${codexMarketplacePath}`)
-    filesWritten++
-  } else {
-    console.log(`Codex marketplace up to date: ${codexMarketplacePath}`)
+  let written = 0
+  for (const { label, path, doc } of targets) {
+    if (writeIfChanged(path, JSON.stringify(doc, null, 2) + "\n")) {
+      console.log(`${label} marketplace written: ${path}`)
+      written++
+    } else {
+      console.log(`${label} marketplace up to date: ${path}`)
+    }
   }
+  return written
+}
 
-  // Generate Cursor marketplace.json from the Claude one (local plugins only).
-  const cursorMarketplace = toCursorMarketplace(marketplaceJson)
-  const cursorMarketplacePath = join(ROOT, ".cursor-plugin", "marketplace.json")
-  const cursorWritten = writeIfChanged(cursorMarketplacePath, JSON.stringify(cursorMarketplace, null, 2) + "\n")
-  if (cursorWritten) {
-    console.log(`Cursor marketplace written: ${cursorMarketplacePath}`)
-    filesWritten++
-  } else {
-    console.log(`Cursor marketplace up to date: ${cursorMarketplacePath}`)
-  }
+/**
+ * Generate Codex, Antigravity, and Cursor manifests for every local plugin so
+ * the same plugin directory loads across runtimes.
+ */
+export async function generateMultiFormat() {
+  const marketplaceJson = loadMarketplace()
+
+  console.log("Generating Codex + Antigravity + Cursor manifests for local plugins...\n")
+  const run = processPlugins(localEntriesByDir(marketplaceJson))
+  const filesWritten = run.filesWritten + writeMarketplaces(marketplaceJson)
 
-  console.log(`\nProcessed ${pluginsProcessed} plugins, wrote ${filesWritten} file(s).`)
-  if (benignSkipped.length > 0) console.log(`Skipped (no manifest): ${benignSkipped.join(", ")}`)
-  if (failed.length > 0) {
-    console.error(`\n${failed.length} plugin(s) failed:`)
-    for (const f of failed) console.error(`  - ${f.name}: ${f.error}`)
+  console.log(`\nProcessed ${run.pluginsProcessed} plugins, wrote ${filesWritten} file(s).`)
+  if (run.benignSkipped.length > 0) console.log(`Skipped (no manifest): ${run.benignSkipped.join(", ")}`)
+  if (run.failed.length > 0) {
+    console.error(`\n${run.failed.length} plugin(s) failed:`)
+    for (const f of run.failed) console.error(`  - ${f.name}: ${f.error}`)
     process.exit(1)
   }
   console.log("Done.")

plugins/plugin-dev/skills/migrating-gemini-extensions/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: Migrating Gemini Extensions
+name: migrating-gemini-extensions
 description: Convert a Gemini CLI extension into a Claude Code plugin, preserving functionality and backwards compatibility. Use when the user wants to migrate/port a Gemini extension to Claude Code, convert gemini-extension.json to plugin.json, adapt GEMINI.md context or Gemini tools/hooks, or mentions "gemini-extension.json", "GEMINI.md", or "migrate Gemini".
 ---
 

plugins/plugin-dev/skills/plugin-authoring/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: Authoring Plugins (Multi-Runtime)
+name: plugin-authoring
 description: Author, scaffold, or edit a plugin once in Claude Code format, then generate the Codex, Antigravity, and Cursor manifests so one directory loads in all four runtimes. Use when creating/scaffolding a new plugin, editing a plugin or its manifest, wiring a marketplace entry, running the multi-format generator, or when the user mentions "plugin.json", ".claude-plugin", ".codex-plugin", ".cursor-plugin", "multi-format", "marketplace.json", "scaffold a plugin", or "Codex/Cursor/Antigravity plugin".
 ---
 

plugins/plugin-dev/skills/plugin-authoring/references/multi-runtime-manifests.md

@@ -11,8 +11,9 @@ is the source of truth; the others are generated.
 | Cursor       | `.cursor-plugin/plugin.json` | none — components auto-discovered     | generated |
 
 Shared assets (`commands/`, `agents/`, `skills/`, `hooks/`) live **once** at the plugin root and are
-referenced by every manifest. Only manifest-level fields differ per runtime. Each generated manifest
-carries its own `$schema`:
+referenced by every manifest. Only manifest-level fields differ per runtime. The Claude source
+manifest and the generated Antigravity manifest each carry a `$schema` (the generated Codex and
+Cursor manifests do not):
 
 - Claude source — `https://json.schemastore.org/claude-code-plugin-manifest.json`
 - Antigravity root `plugin.json` — `https://antigravity.google/schemas/v1/plugin.json`
@@ -36,7 +37,7 @@ For every local plugin (`source: "./plugins/..."`) it emits:
 - `plugins/<name>/.codex-plugin/plugin.json` (+ `.mcp.json` when the plugin defines `mcpServers`)
 - `plugins/<name>/plugin.json` + `mcp_config.json` + root `hooks.json` (Antigravity)
 - `plugins/<name>/.cursor-plugin/plugin.json`
-- `.agents/plugins/marketplace.json` (Codex marketplace, local plugins only)
+- `.agents/plugins/marketplace.json` (Codex marketplace; local plugins plus supported external sources)
 - `.cursor-plugin/marketplace.json` (Cursor marketplace, local plugins only)
 
 It writes only files whose content changed, and prints per-plugin status

plugins/plugin-dev/skills/validating-plugins/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: Validating Plugins
+name: validating-plugins
 description: Thoroughly validate a Claude Code plugin's manifest, directory structure, commands, agents, skills, hooks, and MCP config, then report issues by severity. Use when the user asks to validate, check, audit, or lint a plugin, verify a plugin.json or plugin structure, debug why a plugin won't load, or mentions "plugin validate", "invalid manifest", or "plugin not loading".
 ---