Agent Plugin Porter

agent-plugin-porter ports Claude Code plugin sources into local packages for other agent runtimes.

The default output is a cross-runtime plugin repo:

• Codex CLI/App compatible: .codex-plugin/plugin.json plus a local .agents/plugins/marketplace.json.
• Agy-compatible: root plugin.json.
• Gemini-compatible: gemini-extension.json plus GEMINI.md.

Legacy split targets remain available for target-specific testing:

• codex writes a Codex marketplace package under dist/codex/.
• agy writes an Agy/Gemini-compatible local package under dist/agy/.
• claude is opt-in and writes Claude plugin metadata only when requested.

The first real fixture is Anthropic's official claude-md-management plugin. Existing completed ports such as agent-skills/skills/simplify are reference examples, not input targets.

Install

After the first public npm release:

npm install -g agent-plugin-porter
agent-plugin-porter --help

Or run a published version without installing it globally:

npx -y agent-plugin-porter@latest --help

Until the npm package exists, use the local checkout:

npm ci
npm test
npm run lint
npm run build
npm run cli -- <command>

Port One Plugin

Use a local Claude Code plugin cache path:

npm run build
npm run cli -- port \
  /Users/karlchow/.claude/plugins/cache/claude-plugins-official/claude-md-management/1.0.0 \
  --out ./dist

Use an official GitHub tree URL:

npm run build
npm run cli -- port \
  https://github.com/anthropics/claude-plugins-official/tree/main/plugins/claude-md-management \
  --out ./dist

Generated output:

dist/
├── repo/
│   └── claude-md-management/
│       ├── .agents/plugins/marketplace.json
│       ├── .codex-plugin/plugin.json
│       ├── GEMINI.md
│       ├── commands/revise-claude-md.md
│       ├── gemini-extension.json
│       ├── plugin.json
│       └── skills/claude-md-improver/SKILL.md
└── reports/
    └── claude-md-management.port-report.json

The repo output follows the same multi-harness layout used by obra/superpowers: shared plugin content at the repository root, platform manifests beside it, and runtime-specific marketplace or context files only where a runtime needs them.

Include Claude Plugin Metadata

Claude plugin metadata is opt-in:

npm run cli -- port \
  /Users/karlchow/.claude/plugins/cache/claude-plugins-official/claude-md-management/1.0.0 \
  --targets repo,claude \
  --out ./dist

This adds:

dist/repo/claude-md-management/.claude-plugin/plugin.json
dist/repo/claude-md-management/.claude-plugin/marketplace.json

Use --targets claude only when you specifically want a split Claude package at dist/claude/<plugin-name>/.

Legacy Split Targets

Use split targets when you need the older per-runtime artifacts:

npm run cli -- port \
  /Users/karlchow/.claude/plugins/cache/claude-plugins-official/claude-md-management/1.0.0 \
  --targets codex,agy \
  --out ./dist

Generated split output:

dist/
├── agy/
│   └── claude-md-management/
│       ├── .claude-plugin/plugin.json
│       ├── commands/revise-claude-md.md
│       ├── plugin.json
│       └── skills/claude-md-improver/SKILL.md
├── codex/
│   ├── .agents/plugins/marketplace.json
│   └── plugins/claude-md-management/
│       ├── .codex-plugin/plugin.json
│       ├── commands/revise-claude-md.md
│       └── skills/claude-md-improver/SKILL.md
└── reports/
    └── claude-md-management.port-report.json

Inventory And Batch Port

Inventory a local plugin cache or cloned official repo:

npm run cli -- inventory \
  /Users/karlchow/.claude/plugins/cache/claude-plugins-official \
  --out ./dist/reports/official-inventory.json

Port selected plugins from the inventory:

npm run cli -- port-batch \
  --manifest ./dist/reports/official-inventory.json \
  --include claude-md-management \
  --out ./dist

The inventory command also accepts a GitHub repo URL. For GitHub sources, the repo is cloned into a local .source-cache under the output directory so the inventory paths remain usable by later port-batch commands.

npm run cli -- inventory \
  https://github.com/anthropics/claude-plugins-official \
  --out ./dist/reports/official-inventory.json

Install Generated Repo Output

The default repo output is written to:

dist/repo/claude-md-management

For Codex, register the generated repo as a local marketplace and install the plugin from that marketplace:

codex plugin marketplace add ./dist/repo/claude-md-management
codex plugin marketplace upgrade
codex plugin add claude-md-management@claude-md-management
codex plugin list

For Agy:

agy plugin validate dist/repo/claude-md-management
agy plugin install dist/repo/claude-md-management
agy plugin list

For Gemini CLI legacy extensions:

gemini extensions validate dist/repo/claude-md-management
gemini extensions install dist/repo/claude-md-management
gemini extensions list

Install Legacy Split Codex Output Locally

After --targets codex,agy, copy one generated Codex plugin into the personal marketplace:

npm run cli -- install-codex-personal \
  --plugin claude-md-management \
  --from ./dist/codex

This copies:

dist/codex/plugins/claude-md-management -> ~/plugins/claude-md-management

and updates:

~/.agents/plugins/marketplace.json

Then install from Codex:

codex plugin add claude-md-management@personal
codex plugin list

For a non-default marketplace or sandboxed test, pass explicit paths:

npm run cli -- install-codex-personal \
  --plugin claude-md-management \
  --from ./dist/codex \
  --marketplace /tmp/porter-home/.agents/plugins/marketplace.json \
  --plugins-dir /tmp/porter-home/plugins

Verify Codex Loading

Structural checks:

jq -r '.skills' dist/repo/claude-md-management/.codex-plugin/plugin.json
jq -r '.plugins[0].source.path' dist/repo/claude-md-management/.agents/plugins/marketplace.json
find dist/repo/claude-md-management/skills -maxdepth 3 -type f | sort

Runtime checks:

plugin/read pluginName="claude-md-management"
skills/list forceReload=true

Expected active skill name:

claude-md-management:claude-md-improver

Verify Agy/Gemini Loading

The default package is written to:

dist/repo/claude-md-management

Use the local Agy CLI if available:

agy plugin validate dist/repo/claude-md-management
agy plugin install dist/repo/claude-md-management
agy plugin list

Use Gemini CLI legacy extension commands if available:

gemini extensions validate dist/repo/claude-md-management
gemini extensions install dist/repo/claude-md-management
gemini extensions list

Reports

Each port writes:

dist/reports/<plugin-name>.port-report.json

The report distinguishes mechanical compatibility from semantic portability. For example, claude-md-management is loadable in Codex, but the skill still targets CLAUDE.md, not Codex-native AGENTS.md hygiene. The report preserves that as a semantic warning. Claude command prompt files are copied into generated packages for source completeness, but remain listed under manual components until an explicit target-native command conversion exists.

Always review:

jq '.manualComponents,.semanticWarnings' dist/reports/<plugin-name>.port-report.json

Successful target discovery does not erase manual components. Claude commands, hooks, subagents, MCP configuration, and CLAUDE.md-specific workflows remain manual or semantic-warning surfaces unless this CLI has an explicit, target-specific adapter for them.

Publish-Ready Repo

To publish the default generated repo to GitHub, push this folder as the repository root:

dist/repo/<plugin-name>/.agents/plugins/marketplace.json
dist/repo/<plugin-name>/.codex-plugin/plugin.json
dist/repo/<plugin-name>/gemini-extension.json
dist/repo/<plugin-name>/GEMINI.md
dist/repo/<plugin-name>/plugin.json
dist/repo/<plugin-name>/skills/<skill-name>/SKILL.md

Then add the repository in Codex:

codex plugin marketplace add owner/repo --ref main
codex plugin marketplace upgrade
codex plugin add claude-md-management@claude-md-management

Development

npm ci
npm test
npm run lint
npm run build

CI runs the same verification commands on push and pull requests:

npm ci
npm test
npm run lint
npm run build

Publishing The CLI

Do not publish from an unaudited dirty tree or from an unverified build. The package metadata currently assumes the GitHub home is:

https://github.com/karlorz/agent-plugin-porter

Create that repository before the first public release, or update repository, bugs, and homepage in package.json to match the actual GitHub repository.

Before every publish:

npm ci
npm test
npm run lint
npm run build
npm pack --dry-run
npm view agent-plugin-porter version || true

Inspect the npm pack --dry-run file list. It should include package.json, README.md, LICENSE, and compiled runtime files under build/src/. It should not include src/, test/, dist/, generated port output, source caches, or compiled test files.

First publish usually needs an npm account login or an automation token:

npm login
npm publish

For a prerelease channel:

npm publish --tag beta

If the package is renamed to a public scoped package, publish with explicit public access:

npm publish --access public

For provenance after the npm package exists and GitHub trusted publishing is configured:

npm publish --provenance

Trusted publishing is normally configured from npm package settings after the package exists. Add a publish workflow only after choosing the release trigger and authentication model: either an NPM_TOKEN secret or OIDC trusted publishing with id-token: write.