refactor(plugin-dev): make plugin self-contained and migrate commands to skills (#256)

* refactor(plugin-dev): make plugin self-contained and migrate commands to skills

Move the multi-format generator into plugin-dev so the plugin no longer
depends on repo-root scripts/, add $schema fields to the Claude and
generated Antigravity manifests, and consolidate the 5 slash commands
into 3 skills with a shared references/ folder.

- Move scripts/multi-format.ts and scripts/multi-format.test.ts into
  plugins/plugin-dev/scripts/. Add scripts/run.ts as the CLI entry
  point holding the generateMultiFormat() orchestration previously in
  scripts/cli.ts, which now re-exports it so
  `bun scripts/cli.ts multi-format` keeps working. Extend
  vitest.config.ts to discover the relocated test file.
- Add "$schema" to plugin-dev's .claude-plugin/plugin.json (Claude
  source) and to the generator's Antigravity output (root plugin.json),
  with a new generator test covering the emitted schema URL.
- Fix a pre-existing bug: plugin-dev previously shipped only a
  root-level plugin.json with no .claude-plugin/plugin.json, which
  fails `claude plugin validate`. Migrate the manifest to
  .claude-plugin/plugin.json as the Claude source of truth, with the
  generator producing the root plugin.json as the Antigravity manifest
  — matching the pattern already used by the bun plugin.
- Replace commands/{scaffold,multi-format,validate,best-practices,
  migrate-gemini}.md with three skills modeled on the Codex
  plugin-creator and Cursor create-plugin reference skills:
  skills/plugin-authoring (scaffold + multi-format + best practices,
  with references/{plugin-json-spec,multi-runtime-manifests,
  best-practices}.md), skills/validating-plugins, and
  skills/migrating-gemini-extensions. Update README.md's Commands
  section to Skills and fix the stale claude-at-root comment in the
  generator.

All 132 tests pass; `claude plugin validate plugins/plugin-dev` passes.

* 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

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "plugin-dev",
+  "version": "1.1.0",
+  "description": "Best practices, guidelines, and validation tools for Claude Code plugin development",
+  "author": {
+    "name": "Passion Factory",
+    "email": "support@passionfactory.ai",
+    "url": "https://github.com/pleaseai"
+  },
+  "homepage": "https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/plugin-dev",
+  "repository": "https://github.com/pleaseai/claude-code-plugins",
+  "license": "MIT",
+  "keywords": [
+    "plugin",
+    "development",
+    "best-practices",
+    "validation",
+    "guidelines",
+    "scaffold"
+  ],
+  "skills": [
+    "./skills/"
+  ]
+}

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

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

plugins/plugin-dev/README.md

@@ -4,7 +4,7 @@ Best practices, guidelines, and validation tools for Claude Code plugin developm
 
 ## Overview
 
-`plugin-dev` is a comprehensive toolkit for Claude Code plugin developers. It provides commands, validation hooks, and expert guidance to help you create high-quality plugins that follow best practices.
+`plugin-dev` is a comprehensive toolkit for Claude Code plugin developers. It provides skills, validation hooks, and expert guidance to help you create high-quality plugins that follow best practices. The skills activate automatically when you describe a plugin-development task — no slash commands to remember.
 
 ## Features
 
@@ -28,101 +28,37 @@ claude
 /plugin install plugin-dev@pleaseai
 ```
 
-## Commands
+## Skills
 
-### `/plugin-dev:best-practices`
+These skills activate automatically when your request matches — just describe what you want to do.
+Three focused skills, with deep material factored into `references/` (loaded on demand).
 
-Get comprehensive guidance on Claude Code plugin development best practices.
+### `plugin-authoring`
 
-**Use cases:**
-- Learning plugin development standards
-- Reviewing plugin architecture decisions
-- Understanding component best practices
-- Getting answers to specific development questions
+The umbrella workflow: author, scaffold, or edit a plugin **once** in Claude Code format, then
+generate the Codex, Antigravity, and Cursor manifests from it (`bun scripts/cli.ts multi-format`,
+bundled in this plugin at `scripts/run.ts` + `scripts/multi-format.ts`). Covers scaffolding,
+multi-format generation, and best practices inline, and points to its references:
 
-**Example:**
-```
-/plugin-dev:best-practices
-
-How should I structure my plugin's hooks for optimal performance?
-```
-
-### `/plugin-dev:validate`
-
-Perform comprehensive validation of your plugin structure and configuration.
-
-**Validates:**
-- ✅ Plugin manifest (plugin.json) correctness
-- ✅ Directory structure compliance
-- ✅ Command file formats
-- ✅ Hook configurations
-- ✅ MCP server definitions
-- ✅ Documentation completeness
-
-**Example:**
-```
-/plugin-dev:validate
+- `references/plugin-json-spec.md` — manifest + marketplace field guide with canonical samples.
+- `references/multi-runtime-manifests.md` — per-runtime mapping, the generator, diff scoping.
+- `references/best-practices.md` — quality checklist, pitfalls, testing.
 
-Please validate my plugin at ./plugins/my-plugin
-```
+> "I need a new plugin called *api-tools* for API testing." · "Regenerate *plugins/api-tools*' Codex and Cursor manifests."
 
-### `/plugin-dev:scaffold`
+### `validating-plugins`
 
-Generate a new plugin with proper structure and best practices baked in.
+Audit a plugin's manifest, directory structure, commands, skills, hooks, and MCP config, with
+findings grouped by severity.
 
-**Creates:**
-- Complete directory structure
-- plugin.json manifest
-- Example commands
-- Hook templates
-- README and documentation
-- License and changelog
+> "Validate my plugin at ./plugins/my-plugin."
 
-**Example:**
-```
-/plugin-dev:scaffold
+### `migrating-gemini-extensions`
 
-I need a new plugin called "api-tools" that provides commands for API testing
-```
+Convert a Gemini CLI extension to a Claude Code plugin, preserving functionality and backwards
+compatibility.
 
-### `/plugin-dev:multi-format`
-
-Generate the Codex, Antigravity, and Cursor manifests for the marketplace's local plugins from the
-Claude Code source of truth. The Claude manifest is the only file you author by hand — this command
-keeps every runtime in sync.
-
-**Generates (per local plugin):**
-- `.codex-plugin/plugin.json` (+ `.mcp.json` when MCP is present)
-- root `plugin.json` + `mcp_config.json` + `hooks.json` (Antigravity)
-- `.cursor-plugin/plugin.json`
-- `.agents/plugins/marketplace.json` and `.cursor-plugin/marketplace.json`
-
-**Example:**
-```
-/plugin-dev:multi-format
-
-I just edited plugins/api-tools — regenerate its Codex and Cursor manifests
-```
-
-> The generator rewrites all local plugins; scope your commit to the plugin(s) you changed.
-
-### `/plugin-dev:migrate-gemini`
-
-Migrate existing Gemini CLI extensions to Claude Code plugins.
-
-**Handles:**
-- Converting gemini-extension.json → plugin.json
-- Migrating context files to SessionStart hooks
-- Updating MCP server configurations
-- Maintaining backwards compatibility
-- Updating documentation
-
-**Example:**
-```
-/plugin-dev:migrate-gemini
-
-Help me migrate my Gemini extension at ./extensions/my-extension
-```
+> "Help me migrate my Gemini extension at ./extensions/my-extension."
 
 ## Automatic Validation
 
@@ -194,24 +130,22 @@ plugin-name/
 
 ## Development Workflow
 
-1. **Create plugin structure**
-   ```bash
-   /plugin-dev:scaffold
-   ```
+1. **Create plugin structure** — describe the plugin; the `plugin-authoring` skill activates.
 
 2. **Develop components**
    - Add commands in `commands/`
    - Create agents in `agents/`
+   - Add skills in `skills/`
    - Configure hooks in `hooks/`
 
-3. **Generate multi-runtime manifests**
+3. **Generate multi-runtime manifests** (the `plugin-authoring` skill)
    ```bash
-   /plugin-dev:multi-format
+   bun scripts/cli.ts multi-format
    ```
 
-4. **Validate continuously**
+4. **Validate continuously** — ask to validate the plugin (the `validating-plugins` skill), and run
    ```bash
-   /plugin-dev:validate
+   claude plugin validate plugins/<name>
    ```
 
 5. **Test locally**
@@ -251,7 +185,7 @@ chmod +x hooks/script.sh
 
 ### Validation errors
 **Problem**: Invalid JSON or missing required fields
-**Solution**: Run `/plugin-dev:validate` to see specific issues
+**Solution**: Ask to validate the plugin (the `validating-plugins` skill) to see specific issues
 
 ## Resources
 
@@ -274,7 +208,7 @@ See these plugins for real-world examples:
 Contributions welcome! Please:
 
 1. Follow the best practices outlined in this plugin
-2. Validate your changes with `/plugin-dev:validate`
+2. Validate your changes (the `validating-plugins` skill)
 3. Update documentation
 4. Add examples for new features