Lesson 16.516.5 What a plugin bundles

In everyday life. A bookcase you build yourself arrives in one box. Inside are the boards, a bag of screws and the instructions. A label on the box says what it is, which model, and which version of the instructions. You do not buy the screws one at a time. You install the box.

What you will learn. How to bundle work into one thing people install. What the open standard says the bundle holds. How to add a ready-made link to another system with no code. When you need no bundle at all.

Why it matters. One bundle with a name and a version is what turns a private folder into something a whole team can share and update. It also costs context on every turn, so it must be worth that cost.

What is a plugin?

One installable unit that gives an agent several abilities at once: skills, connectors and, in some products, more. People install, update and remove a plugin as one thing. The Agent Plugins specification, version 1.0.0 (agent-plugins.org, checked November 2, 2026), defines a plugin's portable core. That is the part that moves from one product to another.

brightline-ap/
├── plugin.json          the manifest: required
├── skills/              skills, each to the Agent Skills specification
│   └── invoice-triage/SKILL.md
└── mcp.json             connectors

What does the manifest say?

What the plugin is. The manifest, plugin.json, is at the plugin's root. It is the label on the box. Two fields are required, $schema and name, and most plugins add a version and a description:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "brightline-ap",
  "version": "0.1.0",
  "description": "Brightline Wholesale Supply's accounts payable skills ..."
}

• $schema names the specification's version. Here it pins the plugin to version 1.0.0, which means it fixes the plugin to that exact version.
• name is 1 to 64 lowercase letters, digits, hyphens and periods, starting and ending with a letter or digit, with no -- and no ... Unlike a skill's name, it may have periods. The published schema, at the $schema address, has the full pattern.

The schema lists every field a manifest may have. A product reports an unknown top-level field and then ignores it. Any other mistake in plugin.json, such as a missing name, makes the product reject the whole plugin. A broken mcp.json only turns off that plugin's connectors. The optional fields are in 16.10.

What does a plugin hold?

Exactly two portable parts. Version 1.0.0 defines two components: skills, one folder each under skills/, and connectors, in mcp.json. A connector is either a local program the product starts on your computer or a remote server at an HTTPS address. A skill that breaks the Agent Skills specification is skipped.

Where do hooks and helper agents go?

In an extension, one product's own addition. Hooks, helper agents (subagents) and themes are outside the standard's core. A product that wants them reads them from extensions in plugin.json, or from a top-level folder. Either way, they go under its own reverse-domain name, a web address written backward, such as com.example.client. Products ignore extensions that are not theirs. Some products do not read the core at all yet, and 16.7 shows how one plugin serves them too.

How do I add a connector with no code?

Name a published one, and pin its version. Brightline's plugin names a published filesystem server, pinned to one version and limited to the data folder, in mcp.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "apdata": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@2.1.0", "./data"]
    }
  }
}

Two warnings come with it.

• A connector has the tools its author gave it. This one can also write, move and create files, and a plugin cannot take those tools away. Each product's settings can deny them by name, so the read-only rule is set in the product, as 16.2 said every "never" should be.
• A relative folder depends on where the program starts. Under Agent Plugins, a server started with no working directory starts in the plugin's own folder, so ./data means a data folder inside the plugin. Other products may start it somewhere else. Ask the connector which folders it may read, and check the answer.

Where do secrets go?

Never in a plugin file, because files get shared. That means no key, password or token. Some products let a plugin ask the person installing it for values, and keep a secret one in a secure store (16.10). Agent Plugins 1.0.0 has no field for this.

What does a plugin cost, and when do I need none?

Every enabled plugin adds its skills' descriptions, and its connectors' tool names or descriptions, to every turn, so turn off the ones you rarely use. A skill in a project's own skills folder works with no plugin at all. Package a plugin when you want the same set in many projects, shared with a team, versioned, or in more than one product.

At work. The builder bundles the triage skill, the Monday report and the due list with one data connector, made read-only in each product. The plugin is named brightline-ap. Asked which folders it may read, the connector answers with one path, and the builder checks that it is the folder they meant, the repository's data folder. Getting that folder takes a different setting in each product (16.10).

The operating rule: bundle skills and connectors you will share, and pin every connector to a version. Keep secrets out of every file. Make a connector read-only in each product's settings, not in a sentence.

Figure 16.8. A plugin's portable core is its skills and its connectors. Everything else is an extension for one product.

Practice it. Practice: what a plugin bundles, in your own tool, fifteen minutes.