Review a merge
A merge copies the skills, agents, MCP servers, plugin files and rules of a source into one of your plugins, after you have reviewed in the merge sheet what it adds and what it replaces. A plugin is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and plugin files.
The same sheet opens for four tasks. Each task has its own page, which says where to start it. The sheet reads the source and your plugin when it opens, and nothing changes in your plugin until you apply.
| Task | The source | The title of the sheet | Where the task is described |
|---|---|---|---|
| Pull from a plugin | Another plugin of this project or of another project on the same server | Pull into followed by your plugin's name | Pull from another plugin |
| Merge a library entry | An entry of the plugin library | Merge followed by the entry's name, into and your plugin's name | Merge an entry into a plugin |
| Update from the library | The newer version of the entry your plugin was added from | Update followed by your plugin's name and from the library | Update a plugin added from the library |
| Merge an external plugin | An external plugin previewed on the Imports page | Merge the external plugin into followed by your plugin's name | Import an external plugin |
On Athenode Pro you need the editor or owner role in the project of the plugin that receives the content, as Project roles lists. An update of an external plugin you imported earlier opens a sheet of its own, which can also remove items, and Import an external plugin describes it.
Read what the merge adds and replaces
The sheet lists the source's items under the headings Skills, Agents, MCP servers and Files. A heading appears only when the source has items of that kind. Skills, agents and MCP servers are matched by name, and plugin files by their full path, including the folders. Every item of the source falls into one of three groups.
| Row in the sheet | What it means | What the merge does |
|---|---|---|
| New: followed by the name | Your plugin has no item of that name or path. | Adds it. Every new item is added. |
| A checkbox Replace followed by the name | Your plugin has an item of that name or path, with different content. | Keeps your item, unless you tick the box. |
| The name followed by is identical | Your plugin has the same item already. | Nothing. |
A skill counts as identical when its SKILL.md and all of its bundle files are the same. An MCP server counts as identical when its configuration is the same, and a value that is missing on one side equals an empty value on the other. A plugin file counts as identical when its content is the same.
When the source adds nothing, has no conflict and brings no new rules, the sheet says that your plugin already has everything, and the merge cannot be applied.
Choose the conflicts to replace
Replace a conflicting item when the source's version should take the place of yours, for example a skill that the library entry has improved since you added it.
- Find the item under its heading. Its row starts with a checkbox.
- Tick Replace followed by the item's name for each item whose source version you want.
- Leave the box clear for each item you want to keep as it is.
Every box starts clear, so a merge that you apply without ticking anything adds the new items and leaves every item you have unchanged. Replacing a skill replaces its SKILL.md and its bundle files with the source's.
Conflicts that cannot be replaced
A conflict whose checkbox cannot be ticked stays as it is in your plugin, and the reason is shown in brackets after the name. The merge leaves such an item out in these cases:
- the source or your plugin has two items that match the same name;
- the source's MCP server has the name of an MCP server that one of your agents defines for itself;
- the source's agent defines an MCP server of its own with the name of an MCP server of your plugin;
- a path is a file on one side and a folder on the other;
- the source's item breaks a rule your plugin must follow, such as the 1 to 64 characters of a name or the 50,000 characters of a plugin file.
The same rules apply to a new item. A new item that one of them stops is listed as a conflict that cannot be replaced, and it is not added.
To take such an item anyway, change the name or the path on one side first, in the web UI or with /atn:manage, and open the sheet again.
Choose what happens to the rules
A plugin has one rules text, so the rules are a single choice for the whole merge. The field Rules appears under the items when the source has rules and your plugin has none, or has rules that differ. When the two texts are the same, or the source has no rules, the field is not shown and your rules stay as they are.
| Option | Result |
|---|---|
| "Keep this plugin's rules" | Your rules stay as they are. This is selected when the sheet opens. |
| "Append the source's rules" | The source's rules are added after yours, under a ## heading with the source's name: the source plugin's name, the library entry's name or the external plugin's name. When your plugin has no rules, the source's rules become its rules. |
| "Replace with the source's rules" | The source's rules take the place of yours. |
Rules hold up to 50,000 characters. "Append the source's rules" is not offered when the combined text would be longer, and "Replace with the source's rules" is not offered when the source's rules alone are longer. When you merge an external plugin again from Recent imports on the Imports page, the field starts with the choice you made the last time, where the sheet offers it. Rules in a plugin covers editing the rules afterwards.
Apply the merge
Apply when the ticked boxes and the rules choice are what you want.
- Check every ticked Replace box and the value of Rules.
- Select Apply. In the sheet of a pull, the button is Pull.
Warning
Applying replaces every ticked item and, with "Replace with the source's rules", your rules, without another question. Your earlier version cannot be restored.
The sheet then shows one line with the result, such as "Done: 3 added, 1 replaced, rules kept.", and the button Close. A pull shows "Pulled:" in place of "Done:". A merge is applied as a whole: every item you chose is written, or none is. It never deletes an item from your plugin, and it leaves the source as it is.
If your plugin or the source changed after the sheet read them, for example because an agent edited the plugin in the meantime, nothing is written. A library merge, a library update and an external merge read both sides again and show the new state: check your choices and select Apply again. A pull clears its preview: select Preview and choose again.
The merge changes the plugin in your Athenode project. In each repository where the plugin is installed, run athenode sync to bring the changes into your AI tools, and follow the steps it prints under "Still to do in your tools:". Install a plugin describes sync.
Review a merge from your AI tool
From your AI tool, ask /atn:manage to pull one plugin of the project into another, to merge a library entry into a plugin, to update a plugin from the library or to merge an external plugin. The skill shows you the new, conflicting and identical items first and asks before it replaces anything.
Your AI agent does the same through the Athenode MCP server: each of these tasks has a preview tool and an apply tool, such as plugins_pull_preview and plugins_pull, or library_merge_preview and library_merge. Applied without choices, a merge adds every new item, replaces nothing and keeps your rules. With choices, the agent can also leave out new items, which the web UI always adds. If either side changed since the preview, nothing is written and the agent previews again. Pulling from a plugin of another project is done in the web UI only.