Load portable Agent Plugins

Agent Plugins is a cross-platform specification for Agent extension packages. It uses a purely declarative directory structure to package prompt skills and external tools (MCP servers) together, enabling plug-and-play use and reuse across projects without writing or modifying any Python code.

The bub-agent-plugins plugin gives Bub native support for this specification, automatically discovering and loading the skills and tools in each plugin package.

Get started

Below you will create a plugin package containing a summary skill and a time server. The verification commands call the skill and tool directly and do not require a model API key.

Before you start, install the Bub application and make sure uvx is on PATH.

Install the integration plugins
```
bub install bub-mcp@main bub-agent-plugins@main
bub hooks
```
bub-agent-plugins depends on bub-mcp; install the latest version, and install it explicitly even when you only use skills. The load_state and provide_channels lines from bub hooks should include agent-plugins.
Create the plugin package

Create the following structure in your workspace:
- Directory.agents/
  - Directoryplugins/
    Directoryportable-notes/
    plugin.json
    Directoryskills/
    Directoryplugin-summary/
    SKILL.md
    mcp.json
plugin.json:
```
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "portable-notes",
  "version": "1.0.0",
  "description": "A summary skill and a time server for Bub"
}
```
$schema and name are required fields; skills/ and mcp.json are both optional.

skills/plugin-summary/SKILL.md:
```
---
name: plugin-summary
description: Summarize notes into decisions and next actions.
---

Read the supplied notes. List the decisions made, then the remaining actions and their owners.
If an owner is missing, say that it is unassigned.
```
The skill’s name must match its directory name. Skills with the same name in the workspace or user directories take precedence over skills inside a plugin.
Verify the skill

Run this in the workspace:
```
bub --workspace . run ',skill'
bub --workspace . run ',skill name=plugin-summary'
```
The first command should list plugin-summary; the second should print its location and body. Skills do not need a background channel, so bub run works.
Add and call the MCP server

mcp.json:
```
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "time": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-time"]
    }
  }
}
```
The portable format requires $schema, and every server must declare a type: stdio, streamable-http, or sse. Remote servers use url and optional headers; URLs must use HTTPS except for loopback addresses.

Start the chat interface:
```
bub --workspace . chat
```
Wait for the server to connect, then call the time tool directly:
```
,mcp.portable-notes.time_get_current_time timezone=UTC
```
On first launch, uvx may need to download the server. If you see command not found, check the startup logs and retry after the tool has registered.

Once you have configured a model, you can also let the model call the time tool, or use $plugin-summary to summarize notes.

Use it alongside existing MCP servers

The two kinds of configuration are managed separately and do not affect each other:

Configuration source	Lifecycle channel	Tool name format
`~/.bub/mcp.json`	`mcp.lifecycle`	`mcp.<server>_<tool>`
`<plugin>/mcp.json`	`agent-plugins.mcp`	`mcp.<plugin>.<server>_<tool>`

Both can therefore have a server named time. bub mcp add, remove, and list only manage ~/.bub/mcp.json; servers in a plugin package are verified through the startup logs and the tool name that includes the plugin.

bub chat and bub gateway start the enabled lifecycle channels; bub run does not. When using BUB_ENABLED_CHANNELS, check whether agent-plugins.mcp or mcp.lifecycle is excluded.

Configure discovery paths and components

By default, Bub scans the immediate child directories of <workspace>/.agents/plugins/ and ~/.agents/plugins/. To use other locations, configure them in ~/.bub/config.yml:

agent-plugins:
  paths:
    - /opt/agent-plugins/reporting
  auto_discover: true
  skills_enabled: true
  mcp_enabled: true
  data_root: ~/.bub/agent-plugins

Field	Purpose
`paths`	Explicit plugin root directories, each containing `plugin.json` directly; relative paths resolve against the current workspace
`auto_discover`	When set to `false`, only explicit paths are used
`skills_enabled` / `mcp_enabled`	Enable the skill and MCP components independently
`data_root`	Root directory for persistent plugin data; defaults to `$BUB_HOME/agent-plugins` or `~/.bub/agent-plugins`

Explicit paths take precedence, followed by the workspace directory and then the user directory. When multiple plugin packages have the same manifest name, the first valid package is used.

Environment variables use the BUB_AGENT_PLUGINS_ prefix, with JSON for list values:

export BUB_AGENT_PLUGINS_PATHS='["/opt/agent-plugins/reporting"]'
export BUB_AGENT_PLUGINS_AUTO_DISCOVER=false

Stdio servers receive PLUGIN_ROOT and PLUGIN_DATA as absolute paths, and their default working directory is the plugin root. ${PLUGIN_ROOT} and ${PLUGIN_DATA} expand only in args, env values, and cwd:

{
  "command": "python",
  "args": ["${PLUGIN_ROOT}/server.py"]
}

PLUGIN_DATA points to a persistent directory named after the plugin under data_root. After downloading or updating a plugin package, restart Bub to load the new content.

Troubleshooting

Symptom	What to check
`agent-plugins` is absent from `bub hooks`	Confirm that both integration plugins are installed in the current environment and that the `bub-mcp` version is compatible.
A package is rejected	Check the `$schema` and `name` in `plugin.json`, and inspect the `bub-agent-plugins:` startup logs.
A skill does not appear	Check that `name` matches the directory, whether `skills_enabled` is on, and whether a higher-priority skill has the same name.
An MCP tool does not appear	Check `mcp.json`, `mcp_enabled`, the enabled channels, and the connection logs.
Skills work but MCP does not	The two components load independently; invalid servers are skipped and do not affect skills.