# Plugins & marketplaces

A plugin bundles skills, hooks, subagents and MCP servers into one installable unit; a marketplace is the catalogue that distributes them.

> A plugin is a versioned bundle of agent extensions, installed as one unit. A marketplace is the catalogue where plugins are found and installed from.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/plugins

**Diagram:** A plugin bundles the pieces of a setup, is published in a marketplace, and is installed into many developers' agents.

- Plugin — versioned, one manifest (skills, hooks, subagents, MCP)
- → published in
- Marketplace — catalogue of plugins
- → install
- Many developers:
  - Agent — loads the whole kit

Once you have a good set of skills, hooks and subagents, copying them between repositories by hand breaks down fast. A **plugin** puts them in one package with a manifest that names it, versions it and lists what it contains. Installing the plugin installs all parts. Plugins act before the loop starts: they register their parts with the harness, which then treats them like locally configured skills, hooks and servers.

A **marketplace** is a list of plugins with their sources. Teams often keep one in a repository, so installing and updating the team's kit is a command instead of a copy-and-paste.

## Why it exists

Without packaging, each developer assembles a personal setup. Fixes to a hook reach some machines and not others, and a new colleague starts with nothing. Four developers on four agents drift apart within weeks, and the factory's behavior depends on whose laptop ran the job.

## How it works

**Diagram:** Installing copies files and registers configuration; only the plugin's hooks and servers run code afterwards.

- Plugin — manifest plus a directory per component
- → entry points to it
- Marketplace — source and version
- → you add, install
- Install — copies files, no model runs
- → session start
- Harness loads — usual permissions apply

<warning>

Installing a plugin means running someone else's hooks and servers with your permissions. Pin versions and review a plugin before adding it; see the [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model).

</warning>

Plugins also give you one place to review changes. A pull request against the marketplace repository is a pull request against every developer's setup, which is the point and also the risk.

## Use it when

- More than one person or repository needs the same setup.
- You want versioned, reviewable changes to the shared setup.

## Use something else when

- Only one repository needs the guidance → [Instruction files](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files)
- You have a single procedure to share → [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills)
- You are still designing the individual pieces → [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) or [Subagents](https://ai-sw-factory.mellicci.dev/fundamentals/subagents)

## Key terms

- **Plugin** — a versioned bundle of extensions.
- **Marketplace** — a catalogue of plugins.
- **Manifest** — declares name, version and contents.
- **Pinning** — fixing a version so updates are deliberate.