Migrate an Agent Plugin

August 5, 2026 ยท View on GitHub

Convert an existing plugin to the Agent Plugins v1 portable core without prematurely removing behavior required by its current clients.

Source of truth

Use the current Agent Plugins specification as the normative source.

Read these references before editing:

Workflow

  1. Inventory the current plugin before moving files.

    • Record every manifest, skill, prompt or command, agent, MCP server, hook, LSP server, UI resource, script, secret requirement, and marketplace entry.
    • Identify the clients that currently load each artifact and the install paths or discovery rules they require.
    • Run existing tests or capture a manual smoke-test baseline.

  2. Classify each artifact.

    • Portable core: root plugin.json, Agent Skills in skills/, and MCP servers in root mcp.json.
    • Client extension: additional behavior loaded through a reverse-domain namespace owned and documented by a client.
    • Compatibility layer: legacy files or a generated client package retained until that client supports the portable or namespaced form.
    • Distribution metadata: marketplace catalogs, install policy, signing, and release configuration; these are outside the portable package format.

  3. Add the portable manifest.

    • Create plugin.json at the plugin root.
    • Set $schema to https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.
    • Include name and only supported metadata fields.
    • Do not put component paths or client fields such as hooks, agents, skills, or mcpServers at the top level.

  4. Normalize portable components.

    • Put each skill at skills/<skill-name>/SKILL.md; only immediate children of skills/ are discovered.
    • Make each skill name match its parent directory and the Agent Skills naming rules.
    • If MCP is present, convert it to root mcp.json, declare the matching v1.0.0 schema, and give every server an explicit stdio, streamable-http, or sse type.
    • Use ${PLUGIN_ROOT} for packaged read-only resources and ${PLUGIN_DATA} for persistent writable state where the MCP schema permits expansion.

  5. Preserve non-core behavior.

    • Use a client extension only when the target client publishes a reverse-domain namespace and its semantics.
    • If the client still requires a legacy layout, keep or generate a separate compatibility package. Treat the portable files as the source of truth and avoid manually maintaining divergent copies.
    • Do not invent a vendor namespace and assume an unrelated client will load it.

  6. Validate and test incrementally.

    • Validate the portable manifest, every skill, optional MCP configuration, and package path containment.
    • Test each supported client independently, including hooks and other compatibility behavior.
    • Remove legacy artifacts only after the replacement passes the same behavior checks.

Required migration report

Before finishing, report:

  • The discovered source format and target clients.
  • A mapping from every original artifact to portable core, extension, compatibility layer, distribution metadata, or removal.
  • Files added, moved, generated, retained, and intentionally omitted.
  • Validation and client smoke-test results.
  • Remaining client-specific risks or manual steps.

Prefer an additive, reversible migration. Never claim that hooks, agents, commands, LSP servers, UI, or marketplace metadata became portable Agent Plugins v1 components.