Plugins

A plugin is a versioned folder that bundles capabilities: skills, custom tools, MCP server connections, and optionally a panel that opens beside a Thread. Whorl ships no plugins of its own. Every plugin is a folder your team or a vendor made.

Use a plugin when the same capabilities should reach several layers or companies, or need a version number. For one layer, put skills and tools in that layer directly. See Skills and Tools, MCP servers and connectors.

Add a plugin⁠

  1. Open the Agents card for the layer that should have it. See Agents and setup.
  2. On the Plus everything in line, choose Add plugin.
  3. Choose Upload a plugin folder, then pick the folder.

The plugin is available in that layer on the next run, with nothing else to install. Its skills, tools and servers behave as if they were set up in that layer, and they follow the usual rule that a closer layer's item with the same name wins.

The card shows a plugin by its title and its version. Plugins from outer layers show in the picker for your layer, and you cannot remove them from there.

When a plugin does not work⁠

Whorl marks a plugin it cannot use, with a reason:

  • Unsupported plugin: Whorl cannot read its format.
  • Not working right now: its files couldn't be read or publish it again: re-upload the folder.
  • You don't have access to the place this plugin comes from: ask someone who does.

What is in a plugin⁠

A plugin folder looks like this.

Text
plugins/pricing/
├── plugin.json
├── skills/<name>/SKILL.md
├── tools/<name>/
├── mcp.json
├── hooks/<name>/
└── app/
  • plugin.json names the plugin and gives its version and a description.
  • skills and tools use the same formats as in a layer.
  • mcp.json lists MCP servers to connect. A secret is named, never included.
  • hooks holds code that handles a webhook and turns it into events.
  • app holds a panel, a small app that opens in the Thread's sidebar as a Plugin panel.

To create, check and save one, see The whorl command. The command line scaffolds a plugin with a starter skill.

A plugin's panel and servers can name the secrets they use, and each secret must be set by a person in the layer. A panel never sees a secret's value. See Secrets.

View as Markdown