universal-plugin 0.2.1 → 0.3.0

package/skills/adopt-upx/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: adopt-upx
+description: Use this skill when the user wants to make their skills use upx — the fast local-first package runner shipped by universal-plugin. Trigger on phrases like "make my skills use upx", "adopt the upx runner", "speed up npx calls", "switch to upx", or "rewrite npx pins to upx". Rewrites `npx <pkg>@<version>` references to a caret range on `upx` (`^<major>`, or `^0.<minor>` for a 0.x pin) across one skill, a named set, or every skill in the project.
+---
+
+# Adopt upx
+
+Rewrites `npx <pkg>@<version>` references inside `SKILL.md` files to a caret range on `upx` — the
+fast local-first runner shipped by `universal-plugin` (see the package
+[`readme.md`](../../readme.md#upx--the-fast-package-runner) for the `upx` contract).
+
+## When to use
+
+The user wants their project's skills to shell out via `upx` instead of `npx`, for the ~10× speed
+win on repeated calls. This is an opt-in migration, not a default — see Tradeoff below before
+running it broadly.
+
+## Prerequisites
+
+Install the runner:
+
+```bash
+npm i -g universal-plugin
+```
+
+This puts the `upx` bin on PATH. Verify:
+
+```bash
+upx --help
+```
+
+If `upx` isn't found after install, stop and fix PATH before rewriting anything — a rewritten
+skill with no `upx` on PATH breaks for that user (see Tradeoff).
+
+## Rewrite rule
+
+`npx <pkg>@<version>` → `upx <pkg>@^<major>` — a caret range on the major version, not the exact
+pin. That's the point: one global `upx` install then satisfies every skill's call to that CLI at
+that major, instead of `npx` re-resolving+spawning per exact version every time.
+
+**`0.x` versions are special.** Under semver a `0.x` minor bump is a breaking change, so `^0`
+(= `>=0.0.0 <1.0.0`) is far too loose — it would match across incompatible `0.x` lines. A `0.x` pin
+is rewritten to `upx <pkg>@^0.<minor>` instead (e.g. `pkg@0.2.3` → `upx pkg@^0.2`, matching only the
+`0.2.x` line). `^<major>` applies only to `>=1.0.0`.
+
+Left alone (never rewritten):
+
+- **Non-semver placeholders** — `npx universal-plugin@<version>` (angle-bracket doc placeholders
+  aren't real pins)
+- **Dist-tags** — `npx pkg@next`, `npx pkg@latest` (not a range `upx` can match against an
+  installed version; these already go straight to `npx` inside `upx` itself on a miss)
+- **Already-`upx` references** — nothing to do
+- **Any skill marked `pin-exempt: true`** in its frontmatter — its version strings are
+  documentation/illustration, not real invocations. This mirrors how `plugin bundle` treats
+  pin-exempt skills; `upgrade-plugin` is a live example.
+
+## Choose scope
+
+Ask the user (or infer from their request) which of the three scopes applies:
+
+| Scope | How to invoke |
+|---|---|
+| **A specific skill** | Pass its path: `skills/my-skill` (dir) or `skills/my-skill/SKILL.md` |
+| **A named set** | Pass multiple paths and/or a glob: `skills/a skills/b "skills/foo-*"` |
+| **All skills in the project** | Pass `--all` — walks the whole project for every `SKILL.md`, skipping `node_modules`, `.git`, `dist`, `build`, `.turbo` |
+
+## Run the rewrite
+
+The mechanism is `scripts/rewrite-upx.mjs` in this skill directory — run it directly, don't
+hand-edit files:
+
+```bash
+# One skill
+node "<this skill's dir>/scripts/rewrite-upx.mjs" skills/my-skill
+
+# A named set (paths and/or globs)
+node "<this skill's dir>/scripts/rewrite-upx.mjs" skills/my-skill skills/other-skill "skills/team-*"
+
+# Every skill in the project
+node "<this skill's dir>/scripts/rewrite-upx.mjs" --all
+```
+
+Preview without writing:
+
+```bash
+node "<this skill's dir>/scripts/rewrite-upx.mjs" --all --dry-run
+```
+
+The script reports, per file, how many references it rewrote and which skills it skipped as
+pin-exempt, plus a final tally. It is **idempotent** — re-running over already-rewritten files is
+a no-op (there's no `npx` left to match), so it's safe to run again after adding new skills.
+
+## Tradeoff — say this out loud to the user
+
+A skill rewritten to `upx` now depends on the `upx` bin being on that environment's PATH.
+`npx` always ships with npm — every Node environment has it. `upx` does not — it only exists after
+`npm i -g universal-plugin`. So this is a deliberate opt-in for environments where
+`universal-plugin` is installed globally, not a safe-by-default swap.
+
+Mitigating factor: `upx` itself falls back to plain `npx` on a miss (no local/global install
+satisfies the range) — but that fallback only fires if the `upx` bin is present to run in the
+first place. If `upx` isn't on PATH at all, the shell fails to find the command before `upx`'s own
+fallback logic ever gets a chance to run.
+
+## Verify
+
+1. Re-run the script over the same scope — it should report `0 file(s) rewritten` (idempotent).
+2. Spot-check a rewritten skill: the pin should read `upx <pkg>@^<major>` (or `upx <pkg>@^0.<minor>`
+   for a 0.x package), not a concrete version.
+3. Confirm any pin-exempt skills (e.g. `upgrade-plugin`) were skipped, not rewritten.
+4. If the project has a skill validator (`validate-skill` / `improve-skill`), run it over each
+   touched skill to confirm the rewrite didn't break frontmatter or Markdown structure.
+
+## Commit
+
+Follow project commit discipline — one commit for this rewrite:
+
+```text
+chore(skills): adopt upx runner for <scope>
+```

package/skills/adopt-upx/scripts/rewrite-upx.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Rewrites `npx <pkg>@<version>` references inside SKILL.md files to the fast local-first
+// `upx <pkg>@^<major>` form. See ../SKILL.md for the full contract; this is the mechanism.
+//
+// Usage:
+//   node rewrite-upx.mjs --all                    # every SKILL.md under cwd
+//   node rewrite-upx.mjs skills/my-skill           # one skill (dir or SKILL.md path)
+//   node rewrite-upx.mjs skills/a skills/b/SKILL.md skills/c-*   # a named set (paths + globs)
+//   node rewrite-upx.mjs --all --dry-run           # report only, write nothing
+//
+// Rewrite rule: `npx <pkg>@<concrete-semver>` -> `upx <pkg>@^<major>` (caret on the major, so
+// one global `upx` install serves many pinned callers). A `0.x` pin instead becomes
+// `upx <pkg>@^0.<minor>` — under semver a `0.x` minor bump is breaking, so `^0` would be far too
+// loose. Left alone:
+//   - `@<placeholder>` (non-semver, e.g. `@<version>`) — not a real pin
+//   - dist-tags (e.g. `@next`, `@latest`) — upx can't range-match these, they go to npx anyway
+//   - any occurrence already using `upx` — nothing to rewrite
+//   - any SKILL.md whose frontmatter declares `pin-exempt: true` — its versions are illustration
+//     (the same convention the plugin bundler uses)
+//
+// Idempotent: a second run finds no more `npx <pkg>@<semver>` occurrences to rewrite.
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.turbo'])
+
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/
+const PIN_EXEMPT_PATTERN = /(^|\n)\s*pin-exempt:\s*true\s*(\n|$)/
+
+// Matches `npx <pkg>@<version>` — mirrors the pattern `plugin bundle` uses for pin rewriting,
+// but only for the `npx` runner word (upx refs are already fast, nothing to do). The package
+// class includes `@` and `/` so a scoped package (`@acme/cli@1.2.3`) matches; greedy matching
+// backtracks to the LAST `@`, which separates the version.
+const NPX_REF_PATTERN = /\bnpx(\s+(?:--yes\s+|-y\s+)?)([@a-z0-9/._-]+)@([^\s`'")]+)/g
+
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+function isPinExempt(content) {
+	const match = FRONTMATTER_PATTERN.exec(content)
+	if (!match) return false
+	return PIN_EXEMPT_PATTERN.test(match[1])
+}
+
+// `>=1.0.0` → `^<major>` (any release in that major). A `0.x` version is special: under semver a
+// `0.x` minor bump is a breaking change, so `^0` (= `>=0.0.0 <1.0.0`) is far too loose — pin the
+// minor instead with `^0.<minor>` (= that `0.<minor>.x` line only).
+function caretRange(version) {
+	const [major, minor] = version.split('.')
+	return major === '0' ? `^0.${minor}` : `^${major}`
+}
+
+function rewriteContent(content) {
+	let changed = 0
+	const next = content.replace(NPX_REF_PATTERN, (whole, ws, pkg, version) => {
+		if (!SEMVER_PATTERN.test(version)) return whole // placeholder or dist-tag — leave alone
+		changed++
+		return `upx${ws}${pkg}@${caretRange(version)}`
+	})
+	return { next, changed }
+}
+
+function findSkillFiles(root) {
+	const out = []
+	const st = statSync(root, { throwIfNoEntry: false })
+	if (!st) return out
+	if (st.isFile()) {
+		if (root.endsWith('SKILL.md')) out.push(root)
+		return out
+	}
+	if (st.isDirectory()) {
+		const direct = join(root, 'SKILL.md')
+		if (statSync(direct, { throwIfNoEntry: false })?.isFile()) {
+			out.push(direct)
+			return out // a skill dir given directly — don't also recurse into it
+		}
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			if (entry.isDirectory()) {
+				if (SKIP_DIRS.has(entry.name)) continue
+				out.push(...findSkillFiles(join(root, entry.name)))
+			}
+		}
+	}
+	return out
+}
+
+// Minimal glob: only `*` within a single path segment (no `**`). Enough for named-set patterns
+// like `skills/foo-*` or `skills/*/SKILL.md`.
+function expandGlob(pattern) {
+	if (!pattern.includes('*')) return null
+	const segments = pattern.split('/')
+	let bases = ['.']
+	for (const seg of segments) {
+		if (!seg.includes('*')) {
+			bases = bases.map((b) => join(b, seg))
+			continue
+		}
+		const re = new RegExp('^' + seg.split('*').map(escapeRegExp).join('.*') + '$')
+		const next = []
+		for (const b of bases) {
+			const st = statSync(b, { throwIfNoEntry: false })
+			if (!st?.isDirectory()) continue
+			for (const entry of readdirSync(b)) {
+				if (re.test(entry)) next.push(join(b, entry))
+			}
+		}
+		bases = next
+	}
+	return bases
+}
+
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function resolveTargets(args) {
+	const all = args.includes('--all')
+	const dryRun = args.includes('--dry-run')
+	const positional = args.filter((a) => a !== '--all' && a !== '--dry-run')
+
+	if (all) return { files: findSkillFiles('.'), dryRun }
+
+	const files = []
+	for (const arg of positional) {
+		const globbed = expandGlob(arg)
+		if (globbed) {
+			for (const g of globbed) files.push(...findSkillFiles(g))
+		} else {
+			files.push(...findSkillFiles(arg))
+		}
+	}
+	return { files: [...new Set(files)], dryRun }
+}
+
+function main() {
+	const args = process.argv.slice(2)
+	if (args.length === 0) {
+		console.error('usage: rewrite-upx.mjs (--all | <path-or-glob>...) [--dry-run]')
+		process.exit(1)
+	}
+
+	const { files, dryRun } = resolveTargets(args)
+	if (files.length === 0) {
+		console.error('no SKILL.md files matched — nothing to do')
+		process.exit(0)
+	}
+
+	let touched = 0
+	let skippedExempt = 0
+	for (const file of files) {
+		const abs = resolve(file)
+		const content = readFileSync(abs, 'utf8')
+		if (isPinExempt(content)) {
+			skippedExempt++
+			console.log(`skip (pin-exempt): ${file}`)
+			continue
+		}
+		const { next, changed } = rewriteContent(content)
+		if (changed === 0) continue
+		touched++
+		console.log(`${dryRun ? '[dry-run] ' : ''}rewrite (${changed}): ${file}`)
+		if (!dryRun) writeFileSync(abs, next, 'utf8')
+	}
+
+	console.log(`\n${touched} file(s) rewritten, ${skippedExempt} skipped (pin-exempt), ${files.length} scanned.`)
+}
+
+main()

package/skills/migrate-plugin/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: migrate-plugin
+description: "Move a repository-root universal agent plugin into its npm package so the package distributes its manifest, vendor manifests, skills, and agents. Use this skill when packaging an existing plugin for npm, relocating a top-level plugin into a package, or fixing a package that omits plugin assets, even if the user says only 'ship this plugin through npm' or 'move the plugin into the package.'"
+---
+
+# Migrate Universal Plugin to npm
+
+## Scope
+
+Move one existing universal plugin from a repository root into its owning npm
+package. The package becomes the plugin root and must contain every runtime
+artifact it needs after installation.
+
+This skill does not create a plugin from scratch, publish a package, or move
+project-local agent configuration unrelated to the plugin.
+
+## 1. Inspect and plan
+
+Identify the destination package directory and read its `package.json`.
+Before changing manifest fields or component compatibility behavior, consult the
+[Agent Plugins Specification](https://github.com/agentplugins/agent-plugins-spec)
+and its versioned specification: it is the canonical reference for the current
+standard. Keep an existing schema version pinned unless the user explicitly
+requests a standards upgrade.
+Inventory these root-level plugin assets when they exist:
+
+- `plugin.json`
+- vendor manifest directories for Claude Code, Cursor, Codex, and Copilot CLI
+- `skills/`, `agents/`, `commands/`, `hooks/`, `rules/`, `output-styles/`
+- `.mcp.json`, `.lsp.json`, and plugin-owned `assets/`
+
+Leave project configuration in place unless it is required solely to maintain
+the moved plugin. In particular, do not move `.agents/skills/`, plans, or a
+marketplace catalog such as `.claude/marketplace.json`.
+
+Before modifying files, report the exact source-to-destination mapping and any
+destination collisions. Ask for confirmation if a destination contains a
+different file that would be overwritten.
+
+## 2. Move the plugin root
+
+Move each inventoried asset under the package directory, preserving its path.
+A package receives these relative paths:
+
+```text
+the canonical manifest
+vendor manifests
+skills
+agents
+```
+
+The source root must no longer retain duplicate distributable plugin assets.
+Do not move a project-local skill merely because it is under `.agents/skills/`.
+
+## 3. Configure npm packaging
+
+Add every moved plugin artifact to the destination package's `package.json`
+`files` allowlist. At minimum, include the canonical manifest, each present
+vendor manifest directory, and every present component directory. A typical
+configuration is:
+
+```json
+{
+  "files": [
+    "bin",
+    "dist",
+    "plugin.json",
+    ".claude-plugin",
+    ".cursor-plugin",
+    ".codex-plugin",
+    "skills",
+    "agents"
+  ]
+}
+```
+
+Retain existing package entries such as `bin`, `dist`, and `governances`.
+Never replace the allowlist wholesale.
+
+## 4. Preserve release synchronization
+
+If the repository runs `universal-plugin publish sync-version`, move its
+plugin-specific configuration beside the new `plugin.json` and change
+`packagePath` to `"."`. Update the root release script to run the command from
+the destination package, for example:
+
+```sh
+pnpm exec universal-plugin publish sync-version --root .
+```
+
+Update any checked-in skill lockfile that records an absolute source path for a
+moved skill. Do not modify unrelated agent configuration.
+
+## 5. Verify the result
+
+1. Run the package's focused tests and typecheck/lint commands.
+2. Run `npm pack --dry-run` from the destination package. Confirm it lists
+   `plugin.json`, every required vendor manifest, `skills/`, and `agents/`.
+3. If the manifest declares build targets, run `universal-plugin plugin build`
+   from the destination package and confirm generated paths stay inside it.
+4. Search the repository for stale references to the old top-level asset paths.
+5. Review the diff to confirm no project-local `.agents` content or marketplace
+   catalog was included in the package.
+
+Report the package path, files added to the npm tarball, checks run, and any
+intentionally retained root-local files.

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

@@ -0,0 +1,11 @@
+{
+	"skill_name": "migrate-plugin",
+	"evals": [
+		{
+			"id": 1,
+			"prompt": "Move the top-level universal plugin into packages/universal-plugin so npm distributes it.",
+			"expected_output": "Inventories and relocates only distributable plugin assets, adds them to package.json files, updates version synchronization, verifies npm pack --dry-run, and preserves project-local .agents content.",
+			"files": []
+		}
+	]
+}

package/skills/migrate-plugin/evals/trigger-queries.json

@@ -0,0 +1,35 @@
+{
+	"skill_name": "migrate-plugin",
+	"trigger_queries": [
+		{
+			"id": 1,
+			"query": "Move our root plugin.json and skills into packages/my-plugin so npm ships them.",
+			"should_trigger": true,
+			"split": "train"
+		},
+		{
+			"id": 2,
+			"query": "Our npm package publishes the CLI but not its Claude and Codex plugin assets. Fix the package layout.",
+			"should_trigger": true,
+			"split": "train"
+		},
+		{
+			"id": 3,
+			"query": "Ship this universal agent plugin through npm instead of from the monorepo root.",
+			"should_trigger": true,
+			"split": "val"
+		},
+		{
+			"id": 4,
+			"query": "Upgrade all npx universal-plugin pins to version 0.3.0.",
+			"should_trigger": false,
+			"split": "train"
+		},
+		{
+			"id": 5,
+			"query": "Create a new universal plugin from scratch for Claude Code and Cursor.",
+			"should_trigger": false,
+			"split": "val"
+		}
+	]
+}

package/skills/plugin/README.md

@@ -0,0 +1,37 @@
+# plugin skill
+
+A skill for creating, inspecting, updating, and deleting universal AI coding agent plugins that target multiple runtimes from a single source of truth.
+
+## Supported runtimes
+
+| Vendor      | Manifest path                |
+| ----------- | ---------------------------- |
+| Claude Code | `.claude-plugin/plugin.json` |
+| Cursor      | `.cursor-plugin/plugin.json` |
+| Codex       | `.codex-plugin/plugin.json`  |
+| Copilot CLI | root `plugin.json` (the canonical manifest; nothing derived) |
+
+Universal minimum (no vendor manifest needed): `skills/<name>/SKILL.md` or `.mcp.json`. The canonical source of truth is root `plugin.json`.
+
+## Operations
+
+`SKILL.md` is a gateway: it detects what the project already contains, then routes to one operation
+reference and only that one gets read.
+
+| Operation | Reference | What it covers |
+| --------- | --------- | -------------- |
+| Create | [`references/create.md`](./references/create.md) | scaffold a new plugin with chosen vendors and components |
+| Adopt | [`references/adopt.md`](./references/adopt.md) | put an existing vendor-specific plugin, or already-shipped skills, onto the open standard |
+| Inspect | [`references/inspect.md`](./references/inspect.md) | show build status for each declared vendor |
+| Update | [`references/update.md`](./references/update.md) | add/remove vendors or components |
+| Delete | [`references/delete.md`](./references/delete.md) | remove generated manifests or the whole plugin |
+
+On invocation the gateway checks for existing vendor manifests and publicly-shipped skills, and
+offers adoption when it finds either without a canonical `plugin.json`. Repo-private agent config
+(`.claude/skills/`, `.agents/skills/`) is deliberately excluded — it is not something to package.
+
+## References
+
+- [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)
+- [Schema](https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json)
+- [Examples](https://github.com/cyberuni/universal-plugin/tree/main/examples)

package/skills/plugin/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: plugin
+description: Use this skill when creating, inspecting, updating, versioning, or deleting a universal agent plugin that targets multiple AI coding agent runtimes — Claude Code, Cursor, Codex, GitHub Copilot CLI. Also use it to convert a vendor-specific plugin, or a project that already ships skills, onto the open Agent Plugins Specification, or to move a plugin's version — for asks like "make my Claude Code plugin work in Cursor", "convert this to the open plugin standard", "turn these skills into a plugin", "bump my plugin's version", "release a new version of this plugin", or "set the plugin version to 1.0.0".
+---
+
+# Universal Plugin
+
+Gateway skill. Identify which operation the user wants, load that operation's reference, and follow
+it.
+
+## When to use
+
+When the user wants to create, inspect, update, version, or delete a plugin targeting Claude Code,
+Cursor, Codex, and/or GitHub Copilot CLI from a single source of truth.
+
+## Prerequisites
+
+Load governance before starting any operation:
+
+```bash
+npx universal-plugin governance show plugin-design
+```
+
+Until the CLI is available, read `governances/plugin-design.md` from this plugin's installation
+directory. It is the authoritative source for component selection rules and anti-patterns.
+
+## Step 0 — Detect what is already here
+
+Run this before routing. What the project already contains often changes which operation is
+actually right — a "create a plugin" request in a repo that already ships skills is an *adopt*, not
+a create.
+
+```bash
+ls -d .claude-plugin .cursor-plugin .codex-plugin .github/plugin .plugin 2>/dev/null
+test -f plugin.json && head -20 plugin.json
+find . -name SKILL.md -not -path '*/node_modules/*' -not -path './.git/*'
+```
+
+Read the signals:
+
+| What you find | What it means | Do this |
+|---------------|---------------|---------|
+| Root `plugin.json` with `$schema` on `agent-plugins.org` **and** an `extensions` object | Already on the open standard | Nothing to offer — route normally |
+| A vendor manifest (`.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.github/plugin/`) with **no** canonical root `plugin.json` | A vendor-specific plugin | **Offer to adopt** |
+| Root `plugin.json` with no `$schema`/`extensions` | Legacy single-vendor manifest | **Offer to adopt** |
+| Public skills (see below) and no plugin manifest at all | Skills shipped without a plugin | **Offer to adopt** |
+| None of the above | Greenfield | Route normally |
+
+### Which skills count as public
+
+Only offer on skills the project **distributes**. Repo-local agent configuration is not a plugin,
+and offering to package it is wrong.
+
+| Location | Public? |
+|----------|---------|
+| `skills/<name>/SKILL.md` at the repo root | Yes |
+| `<package>/skills/<name>/SKILL.md` where `package.json` `files` ships it | Yes |
+| `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | **No** — repo-private tooling |
+
+If the only skills are in private locations, say nothing about adoption.
+
+### Making the offer
+
+State what you found, what adoption would give them, and let them decline:
+
+> This repo has a Claude Code plugin manifest but no canonical `plugin.json`. I can convert it to
+> the open Agent Plugins Specification, which would let one manifest drive Cursor, Codex, and
+> Copilot CLI too — Claude Code keeps working exactly as it does now. Want me to?
+
+Offer once. If the user declines, or their request is already a specific unrelated operation
+(deleting manifests, inspecting status), drop it and do what they asked.
+
+## Route
+
+Read exactly the reference for the operation at hand — do not load all six.
+
+| The user wants to… | Reference |
+|--------------------|-----------|
+| Scaffold a new plugin, add vendors/components to a fresh one, or build vendor manifests | [`references/create.md`](./references/create.md) |
+| Put an existing vendor-specific plugin, or already-shipped skills, onto the open standard | [`references/adopt.md`](./references/adopt.md) |
+| See what a plugin declares and which vendor manifests are built or stale | [`references/inspect.md`](./references/inspect.md) |
+| Add or remove a vendor, or add or remove a component, on an existing plugin | [`references/update.md`](./references/update.md) |
+| Bump or set the plugin's version, or cut a release of it | [`references/version.md`](./references/version.md) |
+| Remove generated manifests, or remove the whole plugin | [`references/delete.md`](./references/delete.md) |
+
+If the request spans more than one operation (for example "add Codex and rebuild"), load each
+reference in turn as you reach that part of the work.
+
+If the operation is unclear, ask which the user means rather than guessing.
+
+## Related skills
+
+| Task | Skill |
+|------|-------|
+| Move a repo-root plugin into its npm package | `migrate-plugin` |
+| Publish a packaged plugin to the marketplace | `publish-plugin` |
+| Bump the pinned `universal-plugin@<version>` the project *calls* (not the plugin's own version) | `upgrade-plugin` |
+| Rewrite `npx` pins to the `upx` runner | `adopt-upx` |
+
+## References
+
+- Governance: `npx cyberplace governance show plugin-design`
+- Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
+- Schema: https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json
+- Examples: https://github.com/cyberuni/universal-plugin/tree/main/examples

package/skills/plugin/assets/templates/agent.md

@@ -0,0 +1,7 @@
+---
+name: <agent-name>
+description: Use this agent to <when to invoke>.
+model: sonnet
+---
+
+<agent instructions>

package/skills/plugin/assets/templates/command.md

@@ -0,0 +1,9 @@
+---
+description: <Short description shown in help>
+argument-hint: [optional-arg]
+allowed-tools: [Read, Bash]
+---
+
+# <Command Title>
+
+<instructions>

package/skills/plugin/assets/templates/hooks.json

@@ -0,0 +1,9 @@
+{
+	"description": "<plugin-name> hooks",
+	"hooks": {
+		"PreToolUse": [],
+		"PostToolUse": [],
+		"Stop": [],
+		"UserPromptSubmit": []
+	}
+}

package/skills/plugin/assets/templates/plugin.json

@@ -0,0 +1,19 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "<plugin-name>",
+	"version": "1.0.0",
+	"description": "<description>",
+	"author": { "name": "<author>" },
+	"extensions": {
+		"org.cyberuni.universal-plugin": {
+			"vendors": ["claude-code", "cursor", "codex", "copilot-cli"],
+			"skills": "./skills/",
+			"harnesses": {
+				"claude-code": {},
+				"cursor": {},
+				"codex": {},
+				"copilot-cli": {}
+			}
+		}
+	}
+}

package/skills/plugin/assets/templates/setup-command.md

@@ -0,0 +1,15 @@
+---
+description: Post-install setup — merge always-on plugin guidance into project AGENTS.md
+---
+
+# Plugin Setup
+
+Run once after installing the plugin.
+
+## Instructions
+
+1. Read all `.mdc` files under this plugin's `rules/` directory
+2. Strip YAML frontmatter from each file
+3. Append the remaining content as a new `## <plugin-name>` section in the project's `AGENTS.md`
+4. Confirm the merge completed
+5. The `rules/*.mdc` files are now redundant. Delete them if desired.

package/skills/plugin/assets/templates/skill.md

@@ -0,0 +1,15 @@
+---
+name: <skill-name>
+description: Use this skill when <trigger>. <One-line summary.>
+---
+
+# <Title>
+
+## When to use
+
+<conditions>
+
+## Instructions
+
+1. First step
+2. Second step