# Plugins

> Bundle skills, tools, MCP servers and a panel into one versioned plugin, upload it to a layer, and see which plugins agents have.

Source: https://docs.whorl.work/agents/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](/agents/skills) and [Tools, MCP servers and connectors](/agents/tools).

## Add a plugin

1. Open the **Agents** card for the layer that should have it. See [Agents and setup](/agents/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](/reference/cli). 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](/agents/secrets).

## Related

- [Agents and setup](/agents/setup)
- [Skills](/agents/skills)
- [Tools, MCP servers and connectors](/agents/tools)