# Extensions

> Add agents, skills, tools, lifecycle automation, and capability providers while keeping the
> active surface explicit and reviewable.

Clarvis treats discovery, installation, and activation as separate decisions. Downloading a plugin
does not silently make its code available to an agent. You choose the exact installed items that
belong in an **Extension Profile**, review everything they contribute, and then activate one
resolved snapshot for future runs.

## Understand the four layers

| Layer             | What it does                                                                                         |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| Marketplace       | A catalog that helps you discover plugin packages. It does not activate anything.                    |
| Plugin            | An installed package that can contribute agents, skills, MCP servers, hooks, or capability backends. |
| Standalone skill  | A reusable instruction package installed independently of a plugin.                                  |
| Extension Profile | A complete allow-list that selects exact installed plugins and standalone skills.                    |

A plugin is the atomic activation unit: when selected, all of its declared contributions enter
together. A standalone skill can be selected directly. An Extension Profile never chooses a model
or agent profile, changes tool grants or sandbox policy, stores credentials, or pins package
versions.

## Follow the activation flow

Open `/extensions` and press **Enter** to use the guided composer:

1. choose whether the definition belongs globally or to this workspace;
2. edit a profile, clone the active snapshot, or start with an empty allow-list;
3. search marketplace listings, installed plugins, and standalone skills together;
4. inspect the complete agent, skill, MCP, hook, and executable contribution set;
5. review the exact activation delta, approve workspace-owned executable content when required,
   then apply and reconnect.

Installing from a marketplace row happens before activation. The item is only staged in the draft;
nothing becomes active until you approve the final delta. A successful apply affects new runs. An
in-flight run keeps the immutable extension snapshot it started with.

## Choose the default or an isolated profile

`builtin:default` is a virtual, immutable starting point. It uses the normal plugin activation list
and makes all standalone skill roots available with their standard precedence.

Create a custom Extension Profile when a workspace needs an exact capability set — for example, a
research profile with browser and documentation tools, or a minimal profile that cannot inherit an
unrelated global plugin. Custom profiles are complete allow-lists; they do not add to
`builtin:default` and they do not inherit from one another.

## Keep activation local and auditable

Profile definitions may be global or workspace-scoped. A workspace definition can be committed and
shared, but the selected profile is machine-local state: cloning a repository cannot activate
executable content by itself.

Workspace plugins require approval for their exact executable inventory. Clarvis fingerprints the
resolved contribution bytes and trust state, records the profile id and fingerprint with runs and
sessions, and fails closed if selected content changes. Use `/reconnect` after an intentional
change so the next run receives a fresh snapshot.

## Choose the right extension guide

| You want to…                                    | Read                                                        |
| ----------------------------------------------- | ----------------------------------------------------------- |
| compose and select an exact capability set      | [Extension Profiles](/guide/extension-profiles)             |
| give agents reusable, on-demand instructions    | [Skills](/guide/skills)                                     |
| connect an external tool or prompt server       | [MCP servers](/guide/mcp-servers)                           |
| run automation around lifecycle events          | [Hooks](/guide/hooks)                                       |
| package several contributions together          | [Plugins](/guide/plugins)                                   |
| publish or consume plugin catalogs              | [Marketplaces](/guide/marketplaces)                         |
| inspect file formats, limits, and status states | [Extensions reference](/reference/extensions)               |
| understand scope and executable approval        | [Scopes and workspace trust](/explanation/scopes-and-trust) |

---

[Canonical HTML](https://clarvis.dev/guide/extensions)

[Documentation index](https://clarvis.dev/llms.txt)