refactor(plugin-dev): make plugin self-contained and migrate commands to skills#256
Merged
Merged
Conversation
… 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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR restructures plugin-dev from slash-commands to Skills (plugin-authoring, validating-plugins, migrating-gemini-extensions), removes old command markdown files, relocates the multi-format generator to plugins/plugin-dev/scripts/run.ts (re-exported from scripts/cli.ts), adds an Antigravity ChangesSkills-based plugin-dev refactor and generator relocation
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant CLI as scripts/cli.ts
participant Run as run.ts (generateMultiFormat)
participant Marketplace as marketplace.json
participant Plugins as plugin directories
participant MultiFormat as multi-format.ts generator
CLI->>Run: generateMultiFormat()
Run->>Marketplace: loadMarketplace()
Run->>Plugins: processPlugins()
Plugins->>MultiFormat: generateForPlugin(entry)
MultiFormat-->>Plugins: written files or skip reason
Run->>Run: writeMarketplaces() via writeIfChanged
Run-->>CLI: print summary, exit code on failure
Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 Tessl Skill Review
|
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███ 3/3 | The skill is lean and efficient throughout. It assumes Claude's competence with concepts like JSON manifests, MCP servers, bash scripting, and file structures. Every section serves a clear purpose with no unnecessary explanations of what Gemini or Claude Code are. |
| actionability | ███ 3/3 | Provides concrete, executable examples at every step: complete plugin.json schema, working hooks.json config, executable bash script, MCP server configuration, and specific CLI commands for testing. The directory structure is explicit and copy-paste ready. |
| workflow clarity | ███ 3/3 | The 7-phase workflow is clearly sequenced with logical progression from analysis through testing. Phase 7 includes explicit validation steps (debug mode, plugin list, confirm behavior). The checklist provides a final verification loop, and the common issues section serves as error recovery guidance. |
| progressive disclosure | ██░ 2/3 | The skill references external files like ../plugin-authoring/references/best-practices.md and docs/lessons-learned/context7.md, but no bundle files are provided to verify these exist. The content is well-structured with clear sections, but the inline content is moderately long and some details (like the full SessionStart hook example) could potentially be in referenced files. |
Overall: This is a high-quality migration skill that provides a clear, phased workflow with concrete examples at each step. It efficiently covers manifest conversion, context migration (with preferred vs. legacy approaches), MCP server migration, and testing. The only notable weakness is that referenced files cannot be verified and the skill could potentially benefit from splitting some detailed examples into separate reference files.
plugins/plugin-dev/skills/plugin-authoring/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███ 3/3 | Every section is lean and purposeful. No unnecessary explanations of what plugins are or how runtimes work. The ASCII diagram, numbered steps, and anti-patterns all earn their tokens. No filler or concept explanations Claude would already know. |
| actionability | ███ 3/3 | Provides concrete directory structures, exact CLI commands (bun scripts/cli.ts multi-format, claude plugin validate plugins/<name>), specific file paths, and clear do/don't rules. The workflow is copy-paste ready with real commands and paths. |
| workflow clarity | ███ 3/3 | The 5-step workflow is clearly sequenced with explicit validation at step 5, diff-scoping at step 4 to prevent unintended changes, and references to deeper validation via the validating-plugins skill. The feedback loop is implicit but present (validate → fix → re-run). The 'What NOT to do' section adds important guardrails. |
| progressive disclosure | ███ 3/3 | Clean separation: the SKILL.md body provides the overview and workflow, then points to three well-named reference files for deeper content (spec, multi-runtime details, best practices). References are one level deep, clearly signaled with descriptive labels, and all referenced paths match the actual bundle file listing. |
Overall: This is an excellent skill that efficiently communicates a complex multi-runtime plugin authoring workflow. It uses a clear visual diagram, concise numbered steps with concrete commands, well-structured anti-patterns, and appropriate progressive disclosure to reference files. The content is highly actionable while remaining lean.
plugins/plugin-dev/skills/validating-plugins/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ███ 3/3 | The skill is lean and well-structured. It uses checklists with emoji markers (✅/❌/ |
| actionability | ██░ 2/3 | The CLI commands at the top are concrete and executable, and the checklist items are specific. However, the validation checks are described at a checklist level rather than providing executable code or exact commands for each check (e.g., how to verify chmod +x, how to validate semver, how to parse frontmatter). The guidance is specific but not fully copy-paste executable for the manual checks beyond the CLI. |
| workflow clarity | ███ 3/3 | The process section provides a clear 4-step sequence (scan → parse → check → report), and the output format template gives an explicit structure for reporting findings by severity with actionable fixes. The workflow naturally includes validation checkpoints (CLI validator first, then manual checks) and the report format enforces a feedback loop with prioritized next steps. |
| progressive disclosure | ██░ 2/3 | The content is well-organized with numbered sections and clear headers, but everything is inline in a single file. For a skill of this complexity covering 7 distinct validation areas, some sections (like the detailed output format template or per-component validation rules) could benefit from being split into referenced files. However, at ~80 lines it's manageable as a single document. |
Overall: This is a well-structured validation skill that efficiently covers all plugin components with clear checklists and a defined output format. Its main strength is the comprehensive yet concise coverage of validation areas with the severity-based reporting template. The primary weakness is that the individual validation checks are descriptive checklists rather than fully executable validation logic, though the CLI command at the top provides the primary executable entry point.
Suggestions:
- Add concrete examples of common validation failures with their exact error messages and fixes (e.g., show a malformed plugin.json and the expected fix)
- Include executable snippets for manual checks the CLI doesn't cover, such as a bash one-liner to verify script permissions or validate hook event names
To improve your score, point your agent at the Tessl optimization guide. Need help? Jump on our Discord.
Feedback
Report issues with this review at tesslio/skill-review, or send private feedback from your terminal with tessl feedback.
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 230 |
| Duplication | 10 |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Greptile SummaryThis PR makes
Confidence Score: 5/5This looks safe to merge.
Important Files Changed
Reviews (2): Last reviewed commit: "chore(plugin-dev): apply AI code review ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces significant improvements to the plugin development workflow, including the migration of the multi-runtime manifest generator into the plugin-dev plugin itself, the addition of new skills for authoring and validating plugins, and updated documentation for migrating Gemini extensions. The review feedback suggests standardizing script execution by using package.json scripts instead of direct file execution for consistency, and refactoring the generateMultiFormat function in scripts/run.ts to adhere to the organization's 50 LOC function length limit.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
3 issues found across 19 files
Confidence score: 3/5
- In
plugins/plugin-dev/skills/validating-plugins/SKILL.md, the skillnameformat appears invalid (spaces/uppercase), which can prevent discovery/loading and make the validating-plugins skill effectively unavailable after merge — rename it to a compliant lowercase-hyphen identifier (for example,validating-plugins) before merging. - In
plugins/plugin-dev/skills/plugin-authoring/references/multi-runtime-manifests.md, two statements about manifest contents (marketplace.jsonscope and universal$schemapresence) don’t match generator behavior, which can mislead plugin authors and cause incorrect assumptions in downstream docs/processes — update the wording to reflect local + supported external sources and limit$schemaclaims to the manifests that actually include it.
Architecture diagram
sequenceDiagram
participant User as User (Claude Prompt)
participant PluginDev as plugin-dev Skill System
participant AuthorSkill as Authoring Plugin Skill
participant ValidateSkill as Validating Plugins Skill
participant MigrateSkill as Migrating Gemini Skill
participant Reference as references/ Folder
participant GitWorkflow as Developer (Git/CLI)
participant CLI as scripts/cli.ts
participant Generator as scripts/run.ts + multi-format.ts
participant Manifest as .claude-plugin/plugin.json
participant GeneratorTest as Generator Tests
Note over User,Generator: NEW: Skill-Based Activation (Replaces Slash Commands)
User->>PluginDev: "I need a new plugin called api-tools"
PluginDev->>AuthorSkill: Activate "plugin-authoring" skill (auto-detected)
AuthorSkill->>Reference: Load references/plugin-json-spec.md on demand
AuthorSkill->>Reference: Load references/multi-runtime-manifests.md on demand
AuthorSkill->>Reference: Load references/best-practices.md on demand
User->>PluginDev: "Validate my plugin at ./plugins/my-plugin"
PluginDev->>ValidateSkill: Activate "validating-plugins" skill
User->>PluginDev: "Migrate my Gemini extension"
PluginDev->>MigrateSkill: Activate "migrating-gemini-extensions" skill
Note over GitWorkflow,Generator: CLI & Generator Self-Containment
GitWorkflow->>CLI: bun scripts/cli.ts multi-format
CLI->>Generator: NEW: re-export generateMultiFormat()
Generator->>Generator: CHANGED: bundled inside plugin-dev/scripts/
Generator->>Manifest: Read .claude-plugin/plugin.json
Manifest-->>Generator: Manifest + marketplace entries
Generator->>Generator: Generate Codex, Antigravity, Cursor manifests
Generator->>Generator: NEW: Inject $schema into:
Generator->>Generator: - .claude-plugin/plugin.json (Claude)
Generator->>Generator: - Generated root plugin.json (Antigravity)
Note over Generator: Only writes files with changed content
alt New plugin workflow
GitWorkflow->>Manifest: ADD: .claude-plugin/plugin.json with $schema
Manifest-->>GitWorkflow: Claude source of truth
GitWorkflow->>Generator: bun scripts/cli.ts multi-format
Generator->>Generator: Generate root plugin.json (Antigravity) with $schema
end
Note over GeneratorTest: Testing & Validation
GeneratorTest->>Generator: Run multi-format.test.ts
Generator->>GeneratorTest: NEW: Assert $schema in Antigravity output
GeneratorTest->>GeneratorTest: Verify $schema URL matches Antigravity schema
Note over CLI,Generator: Backward Compatibility
GitWorkflow->>CLI: bun scripts/cli.ts multi-format (legacy path)
CLI->>Generator: Delegates to plugin-dev/scripts/run.ts
Generator-->>CLI: Same output as before
CLI-->>GitWorkflow: Works unchanged
Note over PluginDev,Manifest: Manifest Location Change
PluginDev->>Manifest: NEW: Uses .claude-plugin/plugin.json (was root-only)
Manifest-->>PluginDev: Claude validates correctly (fixes validation failure)
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
- 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)
Contributor
Author
|
/gemini review |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
plugins/plugin-dev/skills/migrating-gemini-extensions/SKILL.md (1)
20-20: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSpecify a language for the fenced code block.
markdownlint flags this code block (MD040) as missing a language specifier. Add
textfor the directory tree structure.♻️ Proposed fix
-``` +```text plugin-name/ ├── .claude-plugin/🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plugins/plugin-dev/skills/migrating-gemini-extensions/SKILL.md` at line 20, The fenced directory-tree code block in SKILL.md is missing a language specifier and triggers markdownlint MD040. Update that block to use a language tag, specifically text, so the tree example is rendered and linted correctly. Use the existing fenced block near the directory structure example in the migration guide to locate it.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@plugins/plugin-dev/skills/migrating-gemini-extensions/SKILL.md`:
- Line 20: The fenced directory-tree code block in SKILL.md is missing a
language specifier and triggers markdownlint MD040. Update that block to use a
language tag, specifically text, so the tree example is rendered and linted
correctly. Use the existing fenced block near the directory structure example in
the migration guide to locate it.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: d62b3b44-7250-4b65-a213-63bbfc5b9271
📒 Files selected for processing (20)
plugins/plugin-dev/.claude-plugin/plugin.jsonplugins/plugin-dev/.codex-plugin/plugin.jsonplugins/plugin-dev/README.mdplugins/plugin-dev/commands/best-practices.mdplugins/plugin-dev/commands/migrate-gemini.mdplugins/plugin-dev/commands/multi-format.mdplugins/plugin-dev/commands/scaffold.mdplugins/plugin-dev/commands/validate.mdplugins/plugin-dev/plugin.jsonplugins/plugin-dev/scripts/multi-format.test.tsplugins/plugin-dev/scripts/multi-format.tsplugins/plugin-dev/scripts/run.tsplugins/plugin-dev/skills/migrating-gemini-extensions/SKILL.mdplugins/plugin-dev/skills/plugin-authoring/SKILL.mdplugins/plugin-dev/skills/plugin-authoring/references/best-practices.mdplugins/plugin-dev/skills/plugin-authoring/references/multi-runtime-manifests.mdplugins/plugin-dev/skills/plugin-authoring/references/plugin-json-spec.mdplugins/plugin-dev/skills/validating-plugins/SKILL.mdscripts/cli.tsvitest.config.ts
💤 Files with no reviewable changes (5)
- plugins/plugin-dev/commands/best-practices.md
- plugins/plugin-dev/commands/migrate-gemini.md
- plugins/plugin-dev/commands/multi-format.md
- plugins/plugin-dev/commands/validate.md
- plugins/plugin-dev/commands/scaffold.md
Contributor
|
Warning Gemini encountered an error creating the review. You can try again by commenting |
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
plugin-devself-contained and migrates its 5 slash commands to skills:scripts/multi-format.tsandscripts/multi-format.test.tsintoplugins/plugin-dev/scripts/, with a newplugins/plugin-dev/scripts/run.tsCLI wrapper holding thegenerateMultiFormat()orchestration.scripts/cli.tsnow re-exportsgenerateMultiFormatfrom the plugin sobun scripts/cli.ts multi-formatkeeps working.vitest.config.tsinclude extended to discover the relocated test.$schemafields — added to.claude-plugin/plugin.json(Claude source) and to the generator's Antigravity output (rootplugin.json), with a new generator test. Fixes a pre-existing bug: plugin-dev previously had no.claude-plugin/plugin.json(manifest was root-only), which failedclaude plugin validate. Migrated to a proper.claude-plugin/plugin.jsonas source, with the generator producing the rootplugin.jsonas the Antigravity manifest — matching thebunplugin's pattern.commands/{scaffold,multi-format,validate,best-practices,migrate-gemini}.md; replaced with 3 skills modeled on the Codexplugin-creatorand Cursorcreate-pluginreference skills:skills/plugin-authoring(umbrella: scaffold + multi-format + best-practices, withreferences/{plugin-json-spec,multi-runtime-manifests,best-practices}.md),skills/validating-plugins, andskills/migrating-gemini-extensions. README's Commands section updated to Skills; fixed a stale claude-at-root comment in the generator.Related issue
N/A
Checklist
bun run test— 132 passed)bun run lint)BREAKING CHANGE:note is includedSummary by cubic
Make
plugin-devself-contained and migrate its slash commands to auto-activating skills. Moves the multi-format generator into the plugin, adds$schemato Claude and Antigravity manifests, fixes manifest validation, and ensures skills are exposed in Codex.Refactors
scripts/multi-format.ts(+ test) intoplugins/plugin-dev/scripts/and addedscripts/run.tsas the CLI;scripts/cli.tsnow re-exportsgenerateMultiFormat;vitest.config.tsupdated for the relocated test..claude-plugin/plugin.jsonas the Claude source of truth (generator now produces the root Antigravityplugin.jsonwith its$schemaand sanitised author); added tests and a collision safeguard for root-manifest plugins.scripts/run.tsto keepgenerateMultiFormatconcise.New Features
plugin-authoring(scaffold + multi-format + best practices withreferences/),validating-plugins, andmigrating-gemini-extensions; README updated from Commands to Skills.skillspath in.codex-plugin/plugin.jsonso Codex exposes skills; documentation clarified for$schemausage and Codex marketplace scope.Written for commit 94f318d. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation
Chores