universal-plugin 0.2.1 → 0.3.0

package/skills/publish-plugin/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: publish-plugin
+description: Use this skill whenever the user wants to publish, release, submit, or share a plugin to the universal plugin marketplace so it works across Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on phrases like "publish my plugin", "submit to marketplace", "release plugin", "list my plugin", "share my plugin", or any mention of getting a plugin into the universal registry. The plugin should already be packaged before using this skill.
+---
+
+# Publish Universal Plugin
+
+Guides adding an already-packaged plugin to a marketplace repo by opening a pull request. Each vendor runtime may have its own marketplace manifest file inside the marketplace repo — update every one that exists.
+
+**Default marketplace repo:** `cyberuni/marketplace` (adjust if the user targets a different one)
+
+## Overview
+
+Publishing has three steps:
+
+1. **Pre-flight** — validate the plugin is ready
+2. **Prepare entries** — build the entry for each vendor marketplace file that exists
+3. **Submit PR** — one PR that updates all relevant marketplace files
+
+Work through each step in order. Do not skip pre-flight even if the user says the plugin is ready.
+
+---
+
+## Step 1: Pre-flight validation
+
+Run these checks against the plugin directory. Stop and fix any failures before continuing.
+
+### 1a. Required metadata
+
+Read the plugin's root `plugin.json`. Verify:
+
+- `name` — present, kebab-case (no spaces, no uppercase)
+- `version` — present, valid semver (`x.y.z`)
+- `description` — present, at least 10 characters
+- `author` — present (string or `{name, email}` object)
+- `homepage` or `repository` — at least one present
+- `license` — present (SPDX identifier, e.g. `MIT`, `Apache-2.0`)
+
+### 1b. Vendor manifest files
+
+Each runtime expects its manifest at a specific path. Check all targeted runtimes and verify each has at minimum a `name` field:
+
+| Runtime | Expected path |
+|---|---|
+| Claude Code | `.claude-plugin/plugin.json` |
+| Cursor | `.cursor-plugin/plugin.json` |
+| Codex | `.codex-plugin/plugin.json` |
+| GitHub Copilot CLI | `plugin.json` (root) |
+
+See `references/vendor-requirements.md` for required fields and hook casing rules per vendor.
+
+### 1c. Hook casing check
+
+If the plugin has hooks, verify each vendor manifest uses the correct event name casing:
+
+- Claude Code and Codex: **PascalCase** (`SessionStart`, `PreToolCall`)
+- Cursor and GitHub Copilot CLI: **camelCase** (`sessionStart`, `preToolCall`)
+
+Mixed casing causes silent hook failures at runtime.
+
+### 1d. Skills check (if present)
+
+If the plugin ships skills, each `skills/<name>/SKILL.md` must exist with valid YAML frontmatter containing at minimum `name` and `description`.
+
+### 1e. Report
+
+List what passed and what failed. Do not proceed to Step 2 until all checks pass.
+
+---
+
+## Step 2: Prepare marketplace entries
+
+### 2a. Detect which vendor marketplace files exist
+
+Clone or check out the marketplace repo locally, then look for vendor marketplace files:
+
+| File | Runtime |
+|---|---|
+| `.claude-plugin/marketplace.json` | Claude Code |
+| `.cursor-plugin/marketplace.json` | Cursor |
+
+Only prepare entries for files that actually exist — do not create new vendor marketplace files.
+
+### 2b. Claude Code entry (`.claude-plugin/marketplace.json`)
+
+The richer format. Use this shape:
+
+```json
+{
+  "name": "<plugin-name>",
+  "source": {
+    "source": "url",
+    "url": "<git-clone-url>.git"
+  },
+  "description": "<one-line description>",
+  "author": { "name": "<author>" },
+  "homepage": "<URL>",
+  "repository": "<git-clone-url>",
+  "license": "<SPDX identifier>",
+  "category": "<category>"
+}
+```
+
+**`source`** — use `"source": "url"` with the `.git` clone URL for public repos. Other options: `github` (sparse checkout), `git` (with ref/path), `file`, `directory`.
+
+**`category`** — choose closest: `research`, `skills`, `setup`, `productivity`, `plugin-authoring`.
+
+**`skills`** — if the plugin ships skills users invoke directly, list their relative paths:
+```json
+"skills": ["./skills/my-skill"]
+```
+
+**`strict`** — set `false` unless the plugin requires exact version pinning.
+
+Omit optional fields rather than leaving them empty.
+
+### 2c. Cursor entry (`.cursor-plugin/marketplace.json`)
+
+The simpler format — only three required fields:
+
+```json
+{
+  "name": "<plugin-name>",
+  "source": {
+    "source": "url",
+    "url": "<git-clone-url>.git"
+  },
+  "description": "<one-line description>"
+}
+```
+
+The `source` field supports the same options as Claude Code (`url`, `github`, `git`, `file`, `directory`).
+
+### 2d. Update scenario
+
+If the plugin is already listed (this is an update), find its existing entry, update changed fields, and preserve any curator-added fields not in the standard shape. Do not overwrite `publishedAt` if present — add `"updatedAt": "<today>"` instead.
+
+Show all prepared entries to the user and ask them to confirm before proceeding.
+
+---
+
+## Step 3: Submit PR
+
+Use the `gh` CLI. Confirm commands that affect shared state before running.
+
+### 3a. Get the marketplace repo locally
+
+If the user has write access (org member), work directly:
+
+```bash
+gh repo clone cyberuni/marketplace
+cd marketplace
+```
+
+If a fork is needed:
+
+```bash
+gh repo fork cyberuni/marketplace --clone --remote
+cd marketplace
+git fetch upstream && git merge upstream/main
+```
+
+### 3b. Create a branch
+
+```bash
+git checkout -b add-<plugin-name>
+```
+
+### 3c. Edit all detected marketplace files
+
+For each vendor marketplace file detected in Step 2a, append the plugin entry to its `plugins` array. Preserve formatting and all existing entries exactly. Stage all changed files together.
+
+### 3d. Commit and push
+
+```bash
+git add .claude-plugin/marketplace.json .cursor-plugin/marketplace.json  # whichever exist
+git commit -m "feat: add <plugin-name> v<version>"
+git push origin add-<plugin-name>
+```
+
+### 3e. Open the PR
+
+```bash
+gh pr create \
+  --repo cyberuni/marketplace \
+  --title "Add <plugin-name> v<version>" \
+  --body "$(cat <<'EOF'
+## Plugin
+
+**Name:** <plugin-name>
+**Version:** <version>
+**Author:** <author>
+**License:** <license>
+**Category:** <category>
+
+## Description
+
+<description>
+
+## Runtimes
+
+- [x] Claude Code
+- [x] Cursor
+- [ ] Codex  (no marketplace file)
+- [ ] GitHub Copilot CLI  (no marketplace file)
+
+## Marketplace files updated
+
+- `.claude-plugin/marketplace.json`
+- `.cursor-plugin/marketplace.json`
+
+## Links
+
+- Homepage: <homepage>
+- Repository: <repository>
+
+## Checklist
+
+- [ ] All targeted vendor manifests present and valid
+- [ ] Hook event casing correct per vendor
+- [ ] Semver version string
+- [ ] SPDX license identifier
+- [ ] Entry appended to each detected marketplace file
+EOF
+)"
+```
+
+Return the PR URL to the user when done.
+
+---
+
+## Common failure modes
+
+| Problem | Fix |
+|---|---|
+| Hook events silently don't fire | Check casing: Claude Code/Codex need PascalCase, Cursor/Copilot CLI need camelCase |
+| Codex rejects manifest | `version` and `description` are required by Codex |
+| PR rejected: missing source link | Add `homepage` or `repository` to plugin.json |
+| Name conflict in marketplace | Check existing entries in each marketplace file first |
+| Plugin loads but skills missing | Add `skills` array to the Claude Code marketplace entry |
+
+---
+
+## Reference files
+
+- `references/vendor-requirements.md` — required fields and hook casing rules per runtime

package/skills/publish-plugin/evals/evals.json

@@ -0,0 +1,23 @@
+{
+	"skill_name": "publish-plugin",
+	"evals": [
+		{
+			"id": 1,
+			"prompt": "I've finished building my plugin 'git-summary' — it's in ~/projects/git-summary-plugin. It has skills, hooks for all four runtimes, and I want to publish it to the universal plugin marketplace. Walk me through the full publish process.",
+			"expected_output": "Runs pre-flight validation checks on all four vendor manifests and plugin.json metadata, then prepares the registry entry JSON and guides opening a PR to the registry repo. Should check hook casing per vendor.",
+			"files": []
+		},
+		{
+			"id": 2,
+			"prompt": "I'm trying to submit my 'code-formatter' plugin to the marketplace but I think there might be validation errors. The plugin is at /tmp/code-formatter. Can you check if it's ready and fix any issues before submitting?",
+			"expected_output": "Runs pre-flight checks, identifies specific validation failures (e.g., missing Codex manifest, wrong hook casing on Cursor manifest, missing license field), reports them clearly, and asks user to fix before proceeding to Step 2.",
+			"files": []
+		},
+		{
+			"id": 3,
+			"prompt": "My plugin 'ai-commit' is already published in the universal marketplace at version 1.0.0. I've just released v1.1.0 with some new hooks. How do I update the marketplace listing?",
+			"expected_output": "Recognizes this as an update scenario, reads existing registry entry, runs pre-flight on new version, prepares updated entry preserving existing fields (especially curator_note and original publishedAt), adds updatedAt, submits an update PR.",
+			"files": []
+		}
+	]
+}

package/skills/publish-plugin/references/vendor-requirements.md

@@ -0,0 +1,38 @@
+# Vendor Requirements
+
+## Claude Code
+
+**Manifest path:** `.claude-plugin/plugin.json`
+**Required fields:** `name`
+**Hook casing:** PascalCase (`SessionStart`, `PreToolCall`, `PostToolCall`, `Stop`)
+**Schema:** https://json.schemastore.org/claude-code-plugin-manifest.json
+
+## Cursor
+
+**Manifest path:** `.cursor-plugin/plugin.json`
+**Required fields:** `name`
+**Hook casing:** camelCase (`sessionStart`, `preToolCall`, `postToolCall`)
+**Schema:** https://raw.githubusercontent.com/cursor/plugins/main/schemas/plugin.schema.json
+
+## Codex
+
+**Manifest path:** `.codex-plugin/plugin.json`
+**Required fields:** `name`, `version`, `description`
+**Hook casing:** PascalCase (follows Claude Code convention)
+
+## GitHub Copilot CLI
+
+**Manifest path:** `plugin.json` (root of plugin directory)
+**Required fields:** `name`
+**Hook casing:** camelCase (follows Cursor convention)
+**Notes:** Also searches `.plugin/plugin.json` as a fallback path
+
+## Hook event name reference
+
+| Canonical | Claude Code / Codex | Cursor / Copilot CLI |
+|---|---|---|
+| session start | `SessionStart` | `sessionStart` |
+| session end | `SessionStop` | `sessionStop` |
+| before tool | `PreToolCall` | `preToolCall` |
+| after tool | `PostToolCall` | `postToolCall` |
+| agent stop | `Stop` | `stop` |

package/skills/upgrade-plugin/README.md

@@ -0,0 +1,23 @@
+# upgrade-plugin skill
+
+Upgrades all pinned `universal-plugin@<version>` calls across a project to the latest or a specific version — recognizes both `npx universal-plugin@<version>` and `upx universal-plugin@<version>` (see the `adopt-upx` skill), preserving whichever runner word each reference already uses.
+
+## When to use
+
+When you need to bump the `universal-plugin` version pin in hook files, SKILL.md files, docs, or any other project files.
+
+## What it does
+
+1. Resolves the target version (latest from npm, or user-supplied semver)
+2. Finds every `npx universal-plugin@<version>` and `upx universal-plugin@<version>` occurrence across the project
+3. Confirms the replacement plan with the user
+4. Applies changes using the Edit tool (reviewable diffs), keeping each reference's runner word (`npx` or `upx`) unchanged
+5. Verifies no old pins remain, then commits
+
+Cross-major bumps require explicit confirmation.
+
+## Install
+
+```bash
+npx skills add cyberuni/universal-plugin --skill upgrade-plugin
+```

package/skills/upgrade-plugin/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: upgrade-plugin
+description: Use this skill when upgrading pinned `npx universal-plugin@<version>` calls across a project to a newer version.
+---
+
+# Upgrade Universal Plugin
+
+## When to use
+
+When the user wants to bump the pinned `universal-plugin` version in hook commands, SKILL.md files, docs, or any other project files from the current pinned version to a target version (latest or a specific semver).
+
+Recognizes both runner words — `npx universal-plugin@<version>` and `upx universal-plugin@<version>` (the fast local-first runner, see the `adopt-upx` skill). A reference keeps whichever runner word it already uses; this skill only bumps the version, never changes `npx` to `upx` or vice versa.
+
+## Instructions
+
+### Step 1 — Resolve the target version
+
+If the user supplied a version (e.g. `2.1.0`), use it directly.
+
+Otherwise, fetch the latest published version:
+
+```bash
+npm view universal-plugin version
+```
+
+### Step 2 — Find all pinned calls
+
+Search the project for every occurrence of `npx universal-plugin@` or `upx universal-plugin@`:
+
+```bash
+grep -rnE "(npx|upx) universal-plugin@" . \
+  --include="*.md" --include="*.json" --include="*.yaml" --include="*.yml" \
+  --include="*.ts" --include="*.js" \
+  | grep -v node_modules
+```
+
+Report a summary: how many files, which files, the runner word each uses (`npx` or `upx`), and the versions currently pinned.
+
+If zero occurrences are found, report that there is nothing to upgrade and stop — do not modify files or create a commit.
+
+### Step 3 — Confirm with the user
+
+Show the list of files and the planned replacement, then ask for confirmation before making any changes.
+
+Example summary:
+
+```text
+Found universal-plugin@1.2.3 pins in 4 files:
+  <skill>/SKILL.md (2 occurrences, npx)
+  <hooks-file> (1 occurrence, npx)
+  <docs-file> (1 occurrence, upx)
+
+Replace all with @1.5.0, keeping each occurrence's runner word (npx/upx)? (y/n)
+```
+
+### Step 4 — Apply replacements
+
+For each confirmed file, replace every `npx universal-plugin@<old-version>` with `npx universal-plugin@<target-version>`, and every `upx universal-plugin@<old-version>` with `upx universal-plugin@<target-version>` — bump the version, keep whichever runner word was already there.
+
+Only replace within the same major version by default — cross-major bumps may include breaking changes. Warn the user and ask for explicit confirmation before replacing across major versions.
+
+```bash
+# Dry-run first (review output before applying)
+grep -rnE "(npx|upx) universal-plugin@" <file> | head -20
+```
+
+Apply with the Edit tool, not `sed`, so each change is reviewable.
+
+### Step 5 — Verify
+
+Re-run the search from Step 2 and confirm no old version strings remain (within the same major), for either runner word.
+
+```bash
+grep -rnE "(npx|upx) universal-plugin@" . \
+  --include="*.md" --include="*.json" --include="*.yaml" --include="*.yml" \
+  --include="*.ts" --include="*.js" \
+  | grep -v node_modules
+```
+
+### Step 6 — Commit
+
+Commit the changes following the project commit discipline:
+
+```text
+chore: upgrade npx universal-plugin pin to @<target-version>
+```

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 unional
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.