Lesson 16.716.7 One skill, three bundles

In everyday life. A recipe written in plain English works in any kitchen. The way you deliver a meal kit, a box of ingredients and a recipe, does not. One grocer wants a box with its own label, another wants a bag with a barcode, and a third wants you to bring the ingredients yourself. The recipe card goes in all three unchanged. Only the packaging differs.

What you will learn. What travels from one product to another and what does not. How to write one set of files that many products can use. How to test it everywhere you promise it.

Why it matters. A team rarely uses one AI tool. If each tool needs its own copy of the work, the copies drift, which is Grace's problem from the overview again.

What are a host, a surface and a building agent?

Three words that keep this clear.

• A host is the product that loads a plugin or a skill.
• A surface is a place where a host runs: a chat in a browser, a task on your desktop, a coding agent in a folder.
• A building agent is the coding agent that writes the files. (The builder is still the person who directs it, as in the rest of the chapter.)

Must I build with the host's own agent?

No. A plugin is files, and any coding agent can write any host's files. You can build a plugin for one company's products with another company's coding agent. What matters is that the files meet each host's rules, and the checks from 16.6 prove that, whoever typed them.

What travels?

How do I design one plugin for many hosts?

Build the portable core to the open standards: shared skills, plugin.json and mcp.json. Keep anything that belongs to one host in that host's extension. Where a host does not read the standard yet, add that host's own manifest beside the core, pointing at the same skills/ folder. Never copy a skill into a second folder, because two copies drift.

plugin/
├── plugin.json          the standard core, read by hosts that implement it
├── mcp.json
├── skills/              one copy, shared by every host
├── .host-a/plugin.json  one host's own manifest, until it reads the standard
└── .host-a/mcp.json     that host's own connector file (names here are illustrative)

A third kind of host may read no bundle at all, only a skills folder named in its settings. That works too: its settings point at the same skills/. If a host starts to follow the standard later, you delete its own files, and nothing in the core changes.

Does one bundle behave the same everywhere?

No. Even within one company's products, surfaces load different parts of the same plugin:

• A chat in a browser can load skills. It can also run a skill's script in its own code sandbox, a space that limits what the script can reach, if that is turned on. A chat cannot start a local connector on your computer, and may skip hooks and helper agents.
• A desktop task on your computer can start a local connector, and may run hooks.
• A coding agent in a folder loads nearly everything, including your project's settings.

So a skill that runs the repository's triage command works in a coding agent inside the repository, and fails in a chat, which has no repository. That is why Brightline's triage skill carries a small script of its own in scripts/, with no dependencies. A test proves it gives the same answer as the engine, the tested code that does the sorting. The skill names both routes, the command and the script.

How far do I test?

On every surface you promise. Decide where the plugin must work. Then check every part against the most limited of those surfaces, and run the same request on each one. Record what loaded, what was skipped, whether the numbers matched, and which version each place printed.

At work. Brightline wants the triage skill in all six places its staff use AI: three surfaces from one company, two from another, and an open-source coding agent. The builder writes the core once. One host's own manifest is beside it. The second company's surfaces read the core directly, and the open-source agent's settings point at the shared skills folder. The local data connector works in the coding agents and the desktop task, and is skipped in the browser chats, where people attach the files instead. The skill handles both: if the connector is there, it reads the folder, and if not, it asks for the files.

The operating rule: any building agent can write any host's files. So write one copy of each skill to the open standard, and put each host's own files beside the core. Never copy a skill. Test the same request on every surface you promise.

Figure 16.11. Any building agent can write any host's files. The skills travel everywhere. The bundle around them is read in different ways, and each surface loads a different part.

Practice it. Practice: one skill, three bundles, in your own tools, fifteen minutes.