Agent Plugins

HivemindOS can load local packages built to the Agent Plugins 1.0.0 specification. A package can add portable Agent Skills, MCP servers, or both.

Package layout

The package root is the folder that contains plugin.json:

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       └── references/
└── mcp.json

HivemindOS reads only these fixed 1.0.0 locations: skills from the folders directly inside skills/, and MCP servers from mcp.json at the root. It validates with bundled copies of the official schemas, so inspecting a package fetches nothing from the network.

Inspect and load a plugin

1. Open Skills from Chat or the Shared Brain, then select Plugins.
2. Enter the full path to the package folder.
3. Select Inspect to check the package without importing or starting anything.
4. Review the accepted parts and any warnings.
5. Leave Import skills and/or Connect MCP on, then select Load plugin.

Skills pass the normal HivemindOS skill security checks, then are copied into Skills/agent-plugins/<plugin-name>/<skill-name> in the Shared Brain. Reloading archives the previous copy first. An existing file there that the plugin loader didn’t create is left alone.

MCP servers can use stdio or Streamable HTTP. Each server connects on its own, so one failure doesn’t block the rest. Legacy HTTP+SSE entries are reported and skipped. Unload MCP disconnects the package’s servers but keeps imported skills and plugin data.

Live MCP connections end when HivemindOS restarts; load the package again to reconnect. Imported skills and plugin data stay. HivemindOS never deletes plugin data automatically.

For plugin authors

A stdio server receives two variables:

• PLUGIN_ROOT: the resolved package folder.
• PLUGIN_DATA: a private writable folder under ~/.hivemindos/agent-plugins/data/ that survives reloads and unloads.

${PLUGIN_ROOT} and ${PLUGIN_DATA} are expanded once in args, env values, and cwd, and nowhere else (not the command, URLs, headers, or unknown placeholders). Servers get only a minimal safe environment plus the values declared in mcp.json. They never inherit HivemindOS credentials.

Validation follows the specification’s failure rules:

• An invalid plugin.json rejects the whole package.
• An invalid component location disables only that component type.
• An invalid skill or MCP entry, or a failed connection, skips only that entry.
• Unknown manifest fields and unsupported extensions are reported and ignored.
• Paths, symlinks, commands, working folders, and copied files can’t escape the package folder or its data folder.

Remote MCP URLs must use HTTPS, except for loopback addresses. Cross-origin redirects aren’t followed, and client-generated headers override conflicting package headers.

What stays in your control

Passing inspection means a package is well-formed, not that it is safe. A local stdio server runs with your user’s permissions. Load packages only from sources you trust, and read their warnings first.