Agent Plugins Builder

Build, validate, and use portable Agent Plugins — one CLI to create, migrate, and package Agent Plugins from existing agent setups, skills, and MCP servers.

What It Is

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.

Why Use It

• 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

# 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/[email protected] init
bunx @hiai-gg/[email protected] init

Once installed, the same commands run as agent-plugins (e.g. agent-plugins init).

Create

# Interactive wizard — metadata, skills, MCP servers, README/LICENSE
npx @hiai-gg/[email protected] init

# From a declarative config file (supports skills, MCP, metadata, README, LICENSE)
npx @hiai-gg/[email protected] create --config plugin.yml --output ./my-plugin

# From flags — combine skills and MCP in one plugin
npx @hiai-gg/[email protected] 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 MIT

Examples

Example 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/[email protected] migrate ./my-project --from claude

# Non-interactive / CI creation
npx @hiai-gg/[email protected] init --yes --name my-plugin

Validate

# Validate and package as an archive
npx @hiai-gg/[email protected] package ./my-plugin

# Hand off to Agent Plugin Doctor for deep validation and security auditing
npx @hiai-gg/[email protected] check ./my-plugin

The Collection

HiAI'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 drift

For validation, Agent Plugin Doctor is the canonical validator and security auditor — Builder generates, Doctor checks.

What It Does

Interactive wizard

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 init

All 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).

Create plugins from scratch

# 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"

Migrate from existing agent setups

# 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 vscode

Migration 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

Validate and inspect plugins

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

Supported Migration Sources

| 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.

Standards

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.

Compatible Clients

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.

How It Works

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.

Limitations

• 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 mcpServers is valid per spec but may not be useful.
• OpenCode config.toml parsing uses a lightweight TOML parser; complex nested TOML structures may not be fully supported.

Documentation

• 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

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run build

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for vulnerability reporting.

License

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.