Import an external plugin into a plugin

Importing an external plugin turns a plugin package for AI coding tools into a plugin, or merges it into a plugin your project has. A plugin is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and plugin files. Athenode reads external plugins in the Agent Plugins format (plugin.json) and Claude Code plugins (.claude-plugin/plugin.json), takes their skills, agents, MCP servers and AGENTS.md, and remembers where the external plugin came from so that you can update it later.

You need the owner or editor role in the project.

What an importable external plugin looks like

An external plugin is a plugin package from outside Athenode: a folder with a manifest at its root. This is the layout Athenode reads, with every part except the manifest optional:

my-plugin/
  plugin.json            (or .claude-plugin/plugin.json)
  skills/<name>/SKILL.md
  agents/<name>.md
  mcp.json               (or .mcp.json)
  AGENTS.md
  LICENSE

How each file maps to the plugin

File or field	What it becomes in the plugin
`plugin.json`	The manifest of an Agent Plugins external plugin. Its `$schema` must be exactly `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`, otherwise the import is refused.
`name`	The proposed slug of a new plugin. An external plugin name has 1 to 64 characters: lowercase letters, digits, `.` and `-`. When the project already has a plugin with that slug, a number is added to it.
`displayName`, else `name`	The proposed name of a new plugin.
`description`	The description of a new plugin, shortened when it is longer than a plugin description may be.
`author`, `license`, `homepage`, `repository`	The attribution of the external plugin, shown on the plugin and carried to a library entry published from it.
`.claude-plugin/plugin.json`	The manifest of a Claude Code plugin, with the same fields. It also accepts `author` as a string, `repository` with a `url`, its own `skills` and `agents` paths, and `mcpServers` written inline or as a path. When an external plugin has both manifests, `plugin.json` is read.
`skills/<name>/SKILL.md`	One skill each, with its bundle files. Only the folders directly under `skills/` are read.
`agents/<name>.md`	One agent each. A missing or invalid `name` falls back to the file name. An agent without a `description` is skipped. Other keys of the agent's front matter are dropped with a warning.
`model` of an agent	The agent's Claude Code model when it is `sonnet`, `opus`, `haiku` or `inherit`. A full model name is mapped to its family, such as `claude-sonnet-4-5` to `sonnet`, and anything else is dropped with a warning.
`tools` of an agent	The agent's Claude Code tools.
`mcp.json`	The MCP servers of an Agent Plugins external plugin. Its `$schema` must be `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json`, and it may hold nothing but `mcpServers`. Otherwise no MCP server is imported and the rest of the external plugin is.
`.mcp.json`	The MCP servers of a Claude Code plugin, read when its manifest names none.
A server's transport	`stdio`, `http` or `sse`. `streamable-http` becomes `http`, and `cwd` is dropped with a warning.
A literal value in `env` or `headers`	A `${KEY}` reference when the name looks like a secret, such as a token or a key, with a warning. Any other literal value is kept, with a warning that publishing the plugin is refused until it is a reference.
`AGENTS.md`	The rules of the plugin, in any letter case of the file name. An `AGENTS.md` longer than 50,000 characters is skipped with a warning.
`LICENSE`	The licence of the external plugin when the manifest names none, as Licences of imported external plugins describes.

Where an external plugin can come from

Source	How it is imported
A public GitHub or GitLab repository	Its URL, optionally with `/tree/<ref>/<path>` for a branch and a folder.
A zip file	Uploaded in the web UI, at most 20 MB. Use it for a private external plugin.
A folder on your computer	With `/atn:manage` or the tool `plugins_external_import`, which zips the folder without `.git`, `node_modules` and links, and uploads it.
A marketplace	A repository with `.claude-plugin/marketplace.json`. You pick one of its external plugins. An external plugin that the marketplace lists from another repository or URL is shown as unavailable: import it from its own URL.
A repository of several external plugins	Every `plugins/<name>` folder with a manifest is offered as an external plugin to pick.

Import an external plugin in the web UI

Open Plugins and select Import external plugin.
Under Source, enter the Repository URL, or choose a Zip file, and select Preview.
If the package offers several external plugins, choose the one to import under Choose an external plugin.
Read the preview: the skills, agents and MCP servers the external plugin brings, whether its AGENTS.md becomes the rules, its licence and attribution, the warnings and what is Not imported.
Under Import into, choose A new plugin and check the Name and Slug, or choose An existing plugin and the Plugin.
Select Import, or for an existing plugin Review the merge.

A new plugin is created as a whole or not at all.

A merge into an existing plugin opens the same review page as merging a library entry. You choose which new items to add and how to decide each conflict, and for the rules you choose Keep mine, Append the external plugin's AGENTS.md or Replace with the external plugin's AGENTS.md. Merge an entry into a plugin describes the review page.

What is not imported

Athenode imports skills, agents, MCP servers and the rules. Hooks, commands, the extension folders of other tools named in reverse-domain form, such as com.example.tool/, and every other file are listed under Not imported with a warning. A reference to the external plugin's own folder in an MCP server, such as ${CLAUDE_PLUGIN_ROOT}, is kept with a warning, because the external plugin's scripts are not copied.

Licences of imported external plugins

The licence follows the same rule as importing a skill: an external plugin whose licence reserves all rights, by its manifest or its LICENSE file, is refused with "The external plugin's licence does not allow copying it, so it cannot be imported."

Every other licence is classed in the preview:

Class	When
Free licence	The manifest's `license`, or else the `LICENSE` file, names a known free licence.
Check the terms	The external plugin names a licence that is not a known free licence. The preview carries a warning.
No licence	The external plugin states no licence. The preview carries a warning: ask the author before you reuse it.

The plugin shows the attribution of each imported external plugin: its author, licence, homepage and repository. When you publish the plugin, the library entry shows the same attribution, and the publish page warns about an external plugin without a free licence.

Update an imported external plugin

The plugin remembers each external plugin it was imported from and the skills, agents and MCP servers each one brought. They are listed under Imported external plugins on the plugin.

For an external plugin imported from a URL, select Check for updates. For an external plugin uploaded as a zip, select Upload new version and choose the zip of the new version.
When there is a new version, the review page lists what it adds, what it changed and what it no longer brings. An item you changed in your plugin while the external plugin changed it too is shown as a conflict.
For each item the new version no longer brings, choose Keep in the plugin or Remove from the plugin. A kept item stays as your own and is no longer updated from the external plugin.
Select Update. If you chose to replace or remove anything, confirm it.

Athenode checks an external plugin only when you ask. When nothing changed, it says that the external plugin is up to date. A change you did not take, or an item the new version no longer brings that you neither removed nor kept, is offered again at the next check.

Import an external plugin from your AI tool

source is a repository URL or the path of a local external plugin folder. A package with several external plugins needs pick with the external plugin's name, and without it the import fails with the code "EXTERNAL_PLUGIN_PICK_REQUIRED".

A merge or an update without decisions adds every new item, replaces and removes nothing and keeps your rules. When the target is the installed plugin, the tool also updates the files in your local project directory.

Your AI agent imports and updates external plugins through the tools plugins_external_import_preview, plugins_external_import, plugins_external_sources, plugins_external_update_preview and plugins_external_update of the Athenode MCP server.

Last updated: 2026-10-19