> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> Bundle skills, commands, sub-agents, hooks, and MCP servers into reusable plugin packages.

<Info>
  **Field reference:** [`plugins`](/reference/plugins) — every field, type, default, and tier for this page.
</Info>

Plugins let you package a set of capabilities — skills, commands, sub-agents, hooks, and MCP servers — into a single reusable unit. You can install a plugin on multiple agents or share it with others.

<Note>
  Today the engine consumes two of a plugin's components at chat time: its **MCP servers** (connected as tools) and its **Commands** (a message of the form `[COMMAND:/name]` expands that command's prompt template before the LLM call). **Skills**, **sub-agents**, and **hooks** declared inside a plugin are saved here but not yet active during conversations.
</Note>

## What a plugin contains

| Component       | Description                                                                                                                                                             |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP servers** | External MCP-compatible servers the agent connects to when the plugin is active.                                                                                        |
| **Skills**      | Skill stubs (name + description) bundled with the plugin. Saved but not yet active at chat time.                                                                        |
| **Commands**    | Slash-style commands (name, description, prompt template). Active at chat time — a `[COMMAND:/name]` message expands the command's prompt template before the LLM call. |
| **Sub-Agents**  | Agent definitions (name, description, system prompt, tool restrictions) the plugin contributes. Saved but not yet active at chat time.                                  |
| **Hooks**       | Event hooks declared by the plugin (event, command, description). Saved but not yet active at chat time.                                                                |

Each plugin also has a **Name**, **Description**, and **Version** (must look like `1.0` or `1.2.3`, optionally with a prerelease/build suffix).

## Adding a plugin

1. Open your agent and go to **Plugins** in the sidebar.
2. Click **Add Plugin** to create an empty plugin in-place, or **Add Plugin From Directory** to install one from the plugin directory.
3. Fill in the name, description, and version.
4. Expand the **+ Skills**, **+ Commands**, **+ Agents**, **+ Hooks**, or **+ MCP Servers** sections to add components.
5. Click **Save Changes**.

## Adding components

Inside each expandable section, click the corresponding **Add …** button to add a row. Each row has its own fields (e.g. an MCP server takes a name, URL, and description; a command takes a name, description, and prompt template).

Sub-agent tool restrictions accept a comma-separated list of tool names; the input auto-completes against the agent's available tools.

## Examples

**Hello world — install from the directory.** Click **Add Plugin From Directory**, pick a plugin, and click **Install**. This adds an entry to your plugin list, but its component arrays (MCP Servers, Commands, Skills, Sub-Agents, Hooks) start empty — nothing auto-activates. Open the new plugin card and populate its **MCP Servers** and **Commands** yourself, following the plugin's README.

**Medium — a reusable team toolkit.** Build a plugin named `support-toolkit` that bundles the MCP server for your help-desk, two skills (ticket lookup, canned-response formatter), and a `/escalate` command. Save it once and install it into every support agent you run, so they all share the same tooling without re-entering it.

**Complex — a packaged sub-agent system.** Build a plugin that contributes a **sub-agent** (e.g. a "researcher" with a restricted tool set), the **MCP servers** that sub-agent needs, **hooks** that log its activity, and a **command** that invokes it. The plugin becomes a self-contained extension — a whole specialist capability, its tools, its governance, and its entry point — that travels as one installable unit across your fleet.

## Plugin order

Plugins appear in the list in the order they were added. The engine merges their MCP servers in that order; if two plugins provide servers with the same name, the first one wins.

## Enabling and disabling a plugin

Every plugin carries an `enabled` flag (default `true`). When it is `false`, the engine skips that plugin's MCP servers and commands at chat time — the plugin's configuration stays saved but does nothing.

There is no on/off control for this flag in the dashboard; it can only be set through the [Management MCP](/manage-mcp). Because the `plugins` section is an array, `config.set` writes the whole list, so include every plugin you want to keep and set `enabled: false` on the one you are taking out of service:

```json theme={null}
{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "plugins",
  "data": [
    {
      "name": "support-toolkit",
      "version": "1.0.0",
      "enabled": false,
      "mcp_servers": [],
      "commands": []
    }
  ]
}
```

## Manage via the Management MCP

This page can be configured programmatically through the [Management MCP](/manage-mcp) — useful for AI agents and CI pipelines.

|               |                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------- |
| Endpoint      | `https://manage.agentheya.com/mcp`                                                          |
| Tool          | `config.set`                                                                                |
| Section       | `plugins`                                                                                   |
| Schema (HTTP) | [`GET /api/manage-mcp/schema/plugins`](https://agentheya.com/api/manage-mcp/schema/plugins) |

Example:

```json theme={null}
{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "plugins",
  "data": { /* see schema for accepted fields */ }
}
```

Partial updates are supported — only the fields you include are changed. Call `config.get` to read the current values and `schema.get` (or the HTTP schema URL above) to see the full field list.