# Plugins & marketplaces: example scenario

Package the ticket-service skill, hooks and reviewer subagent as one plugin and publish it in a team marketplace repository.

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

## Scenario

The `ticket-service` team has built a migration [skill](https://ai-sw-factory.mellicci.dev/fundamentals/skills/example-scenario), three [hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks/example-scenario) and a reviewer [subagent](https://ai-sw-factory.mellicci.dev/fundamentals/subagents/example-scenario). They live in one developer's repository copy and home directory. New teammates and the two sibling services copy the files by hand, versions drift, and nobody knows who has which guard.

This page shows one way to fix that: bundle the pieces as the plugin `ticket-service-kit` and publish it in a team marketplace.

## Before → after

| | Before | After |
|---|---|---|
| Onboarding | Hand-copy files from a colleague, hours of trial and error | Add the marketplace once, install one plugin |
| Consistency | Every machine has a different subset | Everyone who installs version 1.0.0 gets the same pieces |
| Version drift | A hook fix reaches some machines and not others | Bump to 1.1.0; teammates update |
| Who has which guard | Unknown | The installed plugin version answers it |

## Design

**Diagram:** One repository holds the marketplace and the plugin; each developer installs the plugin into their own agent.

- Marketplace repo (acme/agent-marketplace):
  - Catalogue — lists ticket-service-kit
  - →
  - ticket-service-kit — version 1.0.0 (skill, hooks, subagent, MCP)
- → install
- Each developer:
  - Agent — pieces appear in every session
  - GITHUB_MCP_TOKEN — stays in their environment

Generic layout; manifest and catalogue file names differ per agent:

```text
agent-marketplace/                  the marketplace repo
├── <catalogue file>                lists plugins and where they live
└── plugins/ticket-service-kit/
    ├── <plugin manifest>           name, version, description
    ├── skills/add-migration/...    SKILL.md, script, reference
    ├── hooks/                      config + format.sh, guard.sh, log.sh
    ├── agents/reviewer ...         the subagent definition
    └── <mcp config>                optional: github server
```

The catalogue entry names `ticket-service-kit` with source `plugins/ticket-service-kit` in the same repository. The MCP definition holds only the variable name `GITHUB_MCP_TOKEN`, never the token.

## What happens at runtime

<steps>

<step title="Add the marketplace once">

You point the agent at `acme/agent-marketplace`. It fetches the catalogue; nothing is installed yet.

</step>

<step title="Install the plugin">

You install `ticket-service-kit`. The agent copies its files and registers the skill, hooks, subagent and server.

</step>

<step title="Pieces appear in every session">

The harness loads them like locally configured ones. Hooks run on every tool call; the model can use the skill and delegate to the reviewer.

</step>

<step title="Bump the version">

A maintainer fixes `guard.sh`, raises the version to 1.1.0 and merges a pull request to the marketplace repository.

</step>

<step title="Teammates update">

Each teammate updates the plugin, or stays on 1.0.0 if they pin it. You can disable or uninstall the plugin at any time.

</step>

</steps>

Some agents let a project's settings recommend or auto-enable the marketplace and plugin for everyone who opens the repository. That removes the manual steps, and it means opening a repository can trigger an install, so review what it enables.

## What can go wrong

| Failure | How you notice | What to do |
|---|---|---|
| A plugin runs code with your permissions (hooks, MCP servers, scripts) | A hook or server does something you did not read | Review the plugin before installing and pin versions; see the [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) |
| A malicious or compromised marketplace | Unexpected new plugin versions or changed hooks | Use only marketplaces you control, require reviews on the repository, pin versions |
| An update breaks a hook for everyone | Edits fail or tool calls block right after updating | Test on one machine first; roll back to the pinned 1.0.0; fix and release 1.1.1 |
| Names clash with local skills or agents | The wrong `add-migration` or `reviewer` runs | Namespace plugin parts where the agent supports it; rename the local copy |
| Plugin formats differ across agents | The plugin loads in one agent and not another | Keep pieces standard (`SKILL.md`) and check each agent's page |