# 16.5 What a plugin bundles (/building-ai-workers/skills-and-plugins/what-a-plugin-bundles) --- type: Document title: "16.5 What a plugin bundles" description: "A plugin is one installable unit, taught through the Agent Plugins 1.0.0 specification: a plugin.json manifest, skills and connectors as the two portable parts, and extensions for everything else. Adding a ready-made connector with no code, and when you need no plugin." status: stable order: 316.05 ksor: owner: team:panaversity audience: [ public ] approval: by: process:panaversity at: 2026-11-02T20:04:18Z chapter: "16" part: III expert_status: co-build concepts: [ "16.5" ] last_verified: 2026-11-02 generated: at: 2026-11-02T20:04:18Z by: esl-rewrite/1.2.0+ksor.1 trust_tier: unverified build_id: sha256:e1fbcb7d9a8f8b9b7cb96875022325c02c9ba4be94cef13b301cbd39a9edad85 dirty: true ksor_version: 0.0.60 --- **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. ```text 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: ```json { "$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](both-ai-vendors.md). ### 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](one-skill-three-bundles.md) 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`: ```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](choosing-the-right-piece.md) 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](both-ai-vendors.md#product-reference)). 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](both-ai-vendors.md#make-a-connector-read-only)). **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. ![One installable box labeled plugin.json, with its name, version and $schema. Inside, the portable core: a skills folder with invoice-triage, ap-triage and due-by-friday, and mcp.json, with connectors as a local program or a remote address. Beside the box, a dashed tray labeled extensions, for hooks, helper agents, themes and commands, one product each, with a note that other products ignore them. A box labeled every turn lists each skill's description, each connector's tool list and a running local process.](img/plugin-bundle.png) *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](both-ai-vendors.md#practice-what-a-plugin-bundles), in your own tool, fifteen minutes.