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

# Plugins

> Install bundles of skills, sub-agents, MCP servers, and hooks from marketplaces

Plugins bundle [skills](/ctor/reference/skills), [sub-agents](/ctor/reference/sub-agents), [MCP servers](/ctor/reference/mcp), and [hooks](/ctor/reference/hooks) so you can install them together from a marketplace. CTOR's plugin system is compatible with the Claude Code plugin ecosystem.

## The Plugins panel

Click **Plugins** in the sidebar to open the panel. This single button replaces the former separate **Skills**, **Sub-Agents**, and **MCP** buttons.

The panel has four tabs:

* **Plugins** — browse marketplaces and install plugins
* **Skills** — everything the old Skills panel offered (see [Skills](/ctor/reference/skills))
* **Agents** — everything the old Sub-Agents panel offered (see [Sub-agents](/ctor/reference/sub-agents))
* **MCP** — everything the old MCP panel offered (see [MCP servers](/ctor/reference/mcp))

The Skills, Agents, and MCP tabs keep all the management features of the panels they replace.

## Adding a marketplace

A marketplace is a GitHub repository — or a local folder — that lists one or more plugins. Until you add one, the **Plugins** tab shows an empty state.

On the **Plugins** tab, type a GitHub repo into the input and click **Add**. Accepted forms:

* `owner/repo`
* `owner/repo@ref` — where `ref` is a branch, tag, or commit SHA
* Any `github.com` URL

To add a marketplace from disk instead, click the folder button and pick a local folder.

Each marketplace appears as its own section listing its plugins. Local sources show a **local** badge; the built-in marketplace (see below) shows a **Built-in** badge instead. Two actions sit on the section:

* **Refresh** — re-fetches the listing and checks for plugin updates
* **Remove** — removes the marketplace, with an inline confirm ("Remove this marketplace? Installed plugins stay.") — not available for the built-in marketplace

### GitHub token authentication

Set a **GitHub token** at the top of the **Plugins** tab to raise GitHub's anonymous rate limit and add private repositories your token can read. Once saved it shows masked (for example `••••1a2b`) — click **Edit** to change it or **Clear** to remove it.

Each GitHub marketplace you add picks how it authenticates, next to the repo input:

| Auth       | Behavior                                                                        |
| ---------- | ------------------------------------------------------------------------------- |
| **global** | Use your saved GitHub token (default)                                           |
| **custom** | Use a separate token just for this marketplace — required before you can add it |
| **none**   | No token — public repositories only                                             |

A marketplace's auth mode shows as an **auth: {mode}** badge in its section header.

<Warning>
  The token is stored locally in plain text, not encrypted. Use a token scoped only to the repositories your marketplaces need.
</Warning>

### Manifest formats

CTOR reads the marketplace manifest in this order:

1. `.bricks-plugin/marketplace.json`
2. `.claude-plugin/marketplace.json`

When both exist, the `.bricks-plugin` format wins. A repository that contains only a `plugin.json` is treated as a single-plugin marketplace.

### Built-in marketplace

CTOR ships with one marketplace built in — **bricks-ctor-agent-skills**, from `mybigday/bricks-ctor-agent-skills`. It's always registered, needs no setup, and refreshes automatically at startup and once a day while CTOR runs; if it can't reach GitHub, it keeps whatever it last cached.

It carries the BRICKS team's official plugins, including **App Templates** (`app-templates`), which turns an existing application into a reusable prompt template — a short requirement list capturing its design, state, and data flow so you can rebuild or remix it. Shipping from the marketplace means these plugins update without an app release.

Its section renders in a highlighted panel pinned to the bottom of the marketplace list, with a **Built-in** badge (hover it for a hint). It has no **Remove** action, and its name is reserved — adding or replacing a marketplace named `bricks-ctor-agent-skills` from any other source fails with "This name belongs to the built-in marketplace and cannot be replaced or removed."

## Plugin cards

Each plugin shows a card with its name, version, and description, plus badges that summarize what it contains and where it is installed:

* **Installed scope** — **Global**, **This project**, or **N projects**
* **MCP ×N** — the number of MCP servers the plugin bundles
* **Hooks** — present when the plugin defines hooks; shows **Hooks (not approved)** until you enable them

Card actions:

| Action                | Description                                                       |
| --------------------- | ----------------------------------------------------------------- |
| **Install**           | Install the plugin (opens the install dialog)                     |
| **Manage**            | Change which skills are installed                                 |
| **Update**            | Available when the marketplace has a newer version                |
| **Uninstall**         | Remove the plugin from the current scope (click again to confirm) |
| **Remove everywhere** | Remove the plugin from every scope                                |

## Installing a plugin

Clicking **Install** opens the **Install {name}** dialog. It starts with a trust note.

<Warning>
  Skills instruct the agent and can read project files. Only install plugins from repositories you trust.
</Warning>

Below the note, the dialog lists everything the plugin provides so you can choose what to install:

* **Skills** are opt-in checkboxes, with **Select all** / **Select none**. A skill shows an **overwrite** badge when a same-named skill already exists in the target scope. A skill whose name collides with a built-in skill shows a **Reserved name** badge and is skipped.
* **Agents** are listed alongside the skills.
* **MCP servers** require explicit per-server consent, under a *MCP servers run local processes* notice. Each server shows its exact resolved command line and is unchecked by default.
* **Hooks** require a single explicit consent, under a *Hooks run local commands on agent events* notice. Click **Enable hooks (N)** to review every event, matcher, and command before you agree.

Components CTOR doesn't support yet are listed as **Not supported yet (ignored)** — this currently includes slash commands.

The install button shows the current selection count, for example **Install (3)**.

### Install scopes

A **Project | Global** segmented control picks the target scope:

* **Global** installs apply to every project and the main chat. Skills land in `~/.bricks-project-desktop/skills/`.
* **Project** installs apply to the open project only. Skills land in `.bricks/skills/`.

Skills installed by a plugin appear in the **Skills** tab with a **plugin: {name}** badge. Plugin-installed agents appear in the **Agents** tab (without a distinguishing badge).

## Updates and safety

* Plugin MCP servers live in a machine-local registry. They are never written into your project's `.mcp.json`.
* MCP approvals are pinned to the command. If a command changes after an update, you must re-approve it.
* Updating replaces unmodified plugin files but never overwrites skills or agents you have edited — your edited copies are kept. The same applies when you uninstall.
* An update re-expands only the skills you chose at install time. Skills newly added in an update need a reinstall to opt in.

## MCP scope and inheritance

The **MCP** tab has its own **Project | Global** switcher.

* **Global** edits the main workspace's `.mcp.json`, labeled *Main workspace — inherited by all projects*.
* A project inherits global servers under its own. Project entries win by name, so the overall precedence is plugin \< inherited \< project.
* Each project has an **Inherit global MCP servers** toggle.
* Inherited servers show a **Global** badge; plugin servers show a **Plugin** badge.

See [MCP servers](/ctor/reference/mcp) for how to configure and manage servers.

## Claude Code compatibility

An existing Claude Code plugin or marketplace works in CTOR unmodified:

* CTOR reads `.claude-plugin/` manifests.
* It resolves `${CLAUDE_PLUGIN_ROOT}` (and `${BRICKS_PLUGIN_ROOT}`) in MCP and hook commands.
* Only skills, agents, MCP servers, and hooks are activated. Other Claude Code component types are ignored.

## Error messages

The installer reports a clear error when it can't add a marketplace or plugin, including:

* An invalid repository spec
* A repository that can't be found, or a private repository your token can't read
* A GitHub rate limit
* A download or extract failure
* A missing or invalid manifest — a bare skill repository can be installed from the **Skills** tab instead
* An unsupported source type