Agent Plugins Builder

Create, convert, and package portable Agent Plugins from existing agent setups, skills, and MCP servers.

Why

The Agent Plugins ecosystem is growing. 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.

Agent Plugins Builder converts between these formats and the portable Agent Plugins standard, so you can write once and use across compatible clients.

Quick Start

# Install globally (npm or bun)
npm install -g @hiai-gg/agent-plugins-builder
bun install -g @hiai-gg/agent-plugins-builder

# Create a new plugin interactively
agent-plugins init

# Migrate from an existing agent setup
agent-plugins migrate ./my-project

# Validate and package as an archive
agent-plugins package ./my-plugin --output ./dist

Or run without installing:

bunx @hiai-gg/agent-plugins-builder init
bunx @hiai-gg/agent-plugins-builder migrate ./my-project --from claude

What It Does

Create plugins from scratch

# From a declarative config file (supports skills, MCP, metadata, README, LICENSE)
agent-plugins create --config plugin.yml --output ./my-plugin

# From flags — combine skills and MCP in one plugin
agent-plugins 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

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

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

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

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 | CLAUD.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 (Working Draft).

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.