universal-plugin

Write one canonical plugin manifest (root plugin.json). Generate the vendor manifests for Claude Code, Cursor, Codex, and GitHub Copilot CLI.

Usage

No install required:

npx universal-plugin <command>

Pin an exact version for reproducible builds:

npx [email protected] <command>

Specification

This package follows the Agent Plugins Specification. That repository is the canonical reference. Consult its versioned specification and releases before you change manifest or component compatibility behavior.

Commands

plugin

Author the canonical manifest and derive everything from it.

npx universal-plugin plugin init                 # scaffold plugin.json
npx universal-plugin plugin init --npm           # also wire an npm package to ship it
npx universal-plugin plugin build                # generate vendor manifests
npx universal-plugin plugin install              # install the working copy into the runtimes it targets
npx universal-plugin plugin uninstall            # take it back out
npx universal-plugin plugin version <bump>       # stamp the version into every place it lives (author bump)
npx universal-plugin plugin version 1.4.0        # explicit number (semantic-release prepareCmd)
npx universal-plugin plugin version --from-package  # take package.json's version (changesets, release-please)

build writes .claude-plugin/plugin.json, .cursor-plugin/plugin.json, and .codex-plugin/plugin.json. Copilot CLI reads the canonical root plugin.json directly, so no fourth file is derived.

install puts the plugin you are editing into each runtime's local plugin directory, so you can use it before publishing anything. It links where the runtime follows a symlink out of the tree, copies where it does not, refuses a destination another plugin owns, and prints the reload each runtime now needs. Installing a published plugin by name stays the runtime's own job.

Each command writes JSON with JSON.stringify. Your repository decides how JSON looks, so run your formatter after any command that writes a manifest.

sync

Move an installed plugin from the runtime that installed it to the others.

npx universal-plugin prepare <vendor-id>              # e.g. claude-code
npx universal-plugin prepare <vendor-id> --scope project --root <path>
npx universal-plugin prepare <vendor-id> --dry-run    # print the action count without writing state
npx universal-plugin sync apply <action-id>

publish

npx universal-plugin publish check-version            # fail when any place carries a different version (read-only, for CI)

publish sync-version and plugin bundle are deprecated aliases of plugin version --from-package and plugin version. They print a warning and are removed in the next minor release.

marketplace

npx universal-plugin marketplace init --codex --root .
npx universal-plugin marketplace add npm:repobuddy --description "Repo automation"
npx universal-plugin marketplace validate --root .

init derives a catalog from the plugins a repository holds. add lists a plugin that lives elsewhere — a path, a GitHub repo (--subdir for a monorepo, --ref/--sha to pin it), an npm package, or another marketplace's entry — so a curating repository never needs a hand-written catalog. validate checks each catalog against the schema its runtime loads and names the key at fault, so a catalog that would be refused at install time is caught in the repository.

Codex caches a local plugin install by its marketplace entry version. After you change packaged plugin files: update the canonical plugin.json version, regenerate the catalog (add --force to replace an existing one), reinstall the plugin, then start a new Codex session. The installed copy and its marketplace entry then carry the same version.

config

Read and write plugin-registered config in .agents/universal-plugin.json.

npx universal-plugin config get --key sdd-plugins
npx universal-plugin config add --key sdd-plugins --entry '{"name":"aces","handles":["agent evaluation"]}'

add appends the entry, or replaces the existing entry with the same name. Both commands print TOON by default; pass --format json for JSON.

Reference documents

This package ships its own documents (plugin-design, slash-invocation, universal-plugin) under references/. Read one with npx @cyberuni/agent-harness reference show <name> in any project that depends on universal-plugin, or, from a skill, with the reference skill in the cyber-agent-harness plugin.

Housekeeping

npx universal-plugin clean                            # remove the asset store
npx universal-plugin self-update <version>            # update the version pin in hook files

upx, the fast package runner

upx now ships as its own package, @repobuddy/upx.

upx <pkg>@^<major> looks for an already-installed version satisfying the range, checking local node_modules first and then global. It spawns that binary directly, skipping the resolve step that costs npx a registry round-trip on every call. When nothing installed matches, it falls back to npx. See its measurements for what that is worth on current npm.

npm i -g @repobuddy/upx
upx cyber-skills@^2 audit validate

Use a caret range on the major rather than an exact pin, so one global install serves every caller. The adopt-upx skill rewrites references to this form.

upx only works once it is installed globally. npx ships with npm, so keep npx as the default anywhere you cannot guarantee that install.

Deprecated: universal-plugin still installs a upx bin that re-exports @repobuddy/upx, so existing global installs keep working. It will be removed in the next major — install @repobuddy/upx directly.

Related

This package publishes a plugin. To set up the agent configuration of a repository you work in, use buddy-agent-harness.

License

MIT