Build, validate, and use portable Agent Plugins — one CLI to create, migrate, and package Agent Plugins from existing agent setups, skills, and MCP servers.
Agent Plugins Builder is a CLI for creating, migrating, and packaging portable Agent Plugins — the vendor-neutral format that bundles Agent Skills and MCP servers for use across compatible AI coding agents.
Multiple AI coding agents — VS Code, Cursor, GitHub Copilot, ChatGPT/Codex, Claude Code, OpenCode — each have their own configuration formats for skills, instructions, and MCP servers. Builder converts between these formats and the portable Agent Plugins standard, so you can write once and use across compatible clients.
- Write once, use everywhere — one plugin works in VS Code, Cursor, GitHub Copilot, ChatGPT/Codex, Claude Code, OpenCode, and Kiro.
- Migrate what you have — convert existing Claude Code, Cursor, Codex, OpenCode, or VS Code/Copilot setups into portable plugins.
- Declarative and reproducible — define a plugin in
plugin.yml; Builder generates the full plugin directory. The 13 plugins in HiAI's collection are built this way (see The Collection). - Spec-valid output — generated plugins validate against the Agent Plugins v1.0.0 specification, and hand off to Agent Plugin Doctor for deep validation and security auditing.
# Install once, globally (npm or bun)
npm install -g @hiai-gg/agent-plugins-builder
bun install -g @hiai-gg/agent-plugins-builder
# Or run without installing — pinned to the current release (npx or bunx)
npx @hiai-gg/agent-plugins-builder@0.0.9 init
bunx @hiai-gg/agent-plugins-builder@0.0.9 initOnce installed, the same commands run as agent-plugins (e.g. agent-plugins init).
# Interactive wizard — metadata, skills, MCP servers, README/LICENSE
npx @hiai-gg/agent-plugins-builder@0.0.9 init
# From a declarative config file (supports skills, MCP, metadata, README, LICENSE)
npx @hiai-gg/agent-plugins-builder@0.0.9 create --config plugin.yml --output ./my-plugin
# From flags — combine skills and MCP in one plugin
npx @hiai-gg/agent-plugins-builder@0.0.9 create --name project-memory \
--skill create-plan --skill report-progress \
--mcp-type stdio --mcp-command "node server.js" --mcp-name my-server \
--version 0.1.0 --author-name "Jane Doe" --license MITExample plugin.yml:
name: my-plugin
version: 0.1.0
description: A test plugin
author:
name: Test Author
license: MIT
skills:
- name: test-skill
description: A test skill
body: |
# Test Skill
This is the body.
mcp:
my-server:
type: stdio
command: node
args: [server.js]
readme: true
license-file: MIT# Migrate from an existing agent setup
npx @hiai-gg/agent-plugins-builder@0.0.9 migrate ./my-project --from claude
# Non-interactive / CI creation
npx @hiai-gg/agent-plugins-builder@0.0.9 init --yes --name my-plugin# Validate and package as an archive
npx @hiai-gg/agent-plugins-builder@0.0.9 package ./my-plugin
# Hand off to Agent Plugin Doctor for deep validation and security auditing
npx @hiai-gg/agent-plugins-doctor@0.0.6 check ./my-pluginHiAI's Agent Plugins collection ships 13 plugins — github, agent-browser, context7, firecrawl, redis, sentry, supabase, figma, cloudflare, notion, docker, kubernetes, postgresql — all built with this CLI. Each plugin is generated from a declarative plugin.yml, and the collection's CI pins the exact Builder release that produced the checked-in artifacts, regenerates all 13 plugins, and fails on any drift — a concrete reproducibility check you can run locally:
git clone https://github.com/HiAi-gg/agent-plugins.git
cd agent-plugins
./scripts/repro-check.sh # regenerates all 13 plugins; fails on driftFor validation, Agent Plugin Doctor is the canonical validator and security auditor — Builder generates, Doctor checks.
init walks you through creating a plugin step by step — metadata, skills (add as
many as you like), MCP servers (stdio, streamable-http, or sse), README/LICENSE,
and output directory — then previews the files before generating:
agent-plugins initAll prompts have sensible defaults you can accept with Enter. The plugin name is validated against the Agent Plugins name pattern. A skill body file is optional — press Enter to get a template body.
Non-interactive / CI usage:
# Use defaults (one example skill, README + LICENSE)
agent-plugins init --yes --name my-plugin
# Same as --yes
agent-plugins init --non-interactive --name my-plugin
# Declarative config — no prompts at all
agent-plugins init --config plugin.yml--yes / --non-interactive also accept --description, --version,
--author-name, --author-email, and --license flags. The output directory
defaults to ./<plugin-name> (or the positional argument).
# Legacy single-purpose forms
agent-plugins create --name project-memory --skills-only
agent-plugins create --name my-mcp-plugin --mcp-only --mcp-type stdio --mcp-command "node server.js"# Auto-detect source format
agent-plugins migrate ./my-project
# Specify source format
agent-plugins migrate ./my-project --from claude
agent-plugins migrate ./my-project --from cursor
agent-plugins migrate ./my-project --from codex
agent-plugins migrate ./my-project --from opencode
agent-plugins migrate ./my-project --from vscodeMigration reports what is portable, what is client-specific, and what is unsupported:
Portable:
✓ 7 skills
✓ 2 MCP servers
Client-specific (not migrated):
⚠ 3 hooks
⚠ 2 custom agents
Unsupported:
✗ lifecycle completion gate
agent-plugins package ./my-plugin # validate and package as <name>.zip
agent-plugins package ./my-plugin --format tar.gz --output ./dist # gzipped tarball
agent-plugins package ./my-plugin --format dir --output ./dist # directory copy
agent-plugins inspect ./my-plugin # show structure
agent-plugins inspect ./my-plugin --json # machine-readable output| Source | Detection | Portable components | Status |
|---|---|---|---|
| Claude Code | CLAUDE.md or .claude/ |
Skills, MCP, instructions | Supported |
| Cursor | .cursor/ |
Skills, MCP | Supported |
| Codex | AGENTS.md or config.toml |
Instructions, MCP (TOML) | Supported |
| OpenCode | AGENTS.md or .opencode/ |
Skills, MCP, instructions | Supported |
| VS Code / Copilot | .github/ or .vscode/ |
Skills, MCP, instructions | Supported |
See Migration Sources for details on what each adapter migrates and what it cannot.
This project targets the Agent Plugins specification v1.0.0.
Agent Plugin Skills follow the Agent Skills specification.
MCP server configuration follows the Model Context Protocol specification.
Agent Plugins v1.0.0 is supported by:
| Client | Skills | MCP transports |
|---|---|---|
| VS Code | ✅ | stdio, Streamable HTTP, SSE |
| Cursor | ✅ | stdio, Streamable HTTP, SSE |
| GitHub Copilot | ✅ | stdio, Streamable HTTP, SSE |
| ChatGPT & Codex | ✅ | stdio, Streamable HTTP |
| Kiro | ✅ | stdio, Streamable HTTP, SSE |
See Compatibility for details and evidence levels.
Claude / Cursor / Codex / OpenCode / VS Code
↓
Agent Plugins Builder (source adapter)
↓
PortablePlugin (canonical model)
↓
Agent Plugins format (generator)
↓
plugin.json + skills/ + mcp.json
All migration adapters produce a source-agnostic PortablePlugin intermediate representation. The generator then emits a valid Agent Plugin directory. This means adding new source formats does not require pairwise conversions.
See Architecture for details.
- Targets Agent Plugins v1.0.0 only. Future spec versions are not yet supported.
- Client-specific hooks, custom agents, and lifecycle handlers are not migrated — they are reported in the migration summary.
- Extension data is preserved opaquely but not validated.
- No OAuth or credential management (by Agent Plugins spec design).
- MCP-only plugins require at least one server. Empty
mcpServersis valid per spec but may not be useful. - OpenCode
config.tomlparsing uses a lightweight TOML parser; complex nested TOML structures may not be fully supported.
- Architecture — package design, data flow, adapter pattern
- Migration Sources — what each adapter migrates
- Spec Support — Agent Plugins v1.0.0 coverage
- Compatibility — client support details
- References — primary sources
- Roadmap — planned work
bun install
bun run lint
bun run typecheck
bun run test
bun run buildSee CONTRIBUTING.md.
See SECURITY.md for vulnerability reporting.
MIT — Copyright © 2026 HiAI
This project is independent and is not affiliated with or endorsed by the Agent Plugins specification maintainers or any supported client vendors.