Step-by-step guide

Curate extensions for your team

Give people one trusted place to discover capabilities your organization supports.

You will build: A Git-backed catalog containing installable plugins.
Time: 15 minutes
Before you start: One or more plugin repositories.

What this changes

An internal catalog turns extension sharing into an intentional practice. Teams can find approved capabilities, understand ownership and adopt them without copying setup from one repository to another.

01
Discoverability
Useful internal capabilities stop depending on word of mouth.
02
Curation
The catalog expresses what the organization is prepared to support.
03
Shared ownership
Every capability can carry a clear home and maintenance expectation.

Minimum setup

Start with one working configuration.

Create marketplace.json at the root of a Git repository. Every entry points to a plugin source; the catalog itself carries no executable behavior and grants no authority.

marketplace.json marketplace

{
  "name": "Acme internal marketplace",
  "plugins": [
    {
      "name": "acme-review",
      "source": "https://git.acme.example/platform/acme-review.git",
      "description": "Review checklists and a reviewer agent."
    }
  ]
}

Why this is the minimum

The plugin name in the catalog must match the name in its own manifest. Installing a listing still does not enable it, and hooks shipped by that plugin still require their own review.

Working patterns

Adapt it to work you actually do.

Open a pattern to see the complete files and the reason behind each choice.

Pattern 01 One repository holding both the catalog and the plugins Configuration

You have a handful of small internal plugins and you do not want to create a git repository per plugin. `source` may point back at the catalog repository itself, with `path` selecting each plugin.

One repository holding both the catalog and the plugins example

Repository layout, all in one git repository:

  clarvis-marketplace/
  ├── marketplace.json
  └── plugins/
      ├── acme-review/
      │   ├── plugin.json
      │   └── skills/
      │       └── review-checklist/
      │           └── SKILL.md
      └── acme-runbooks/
          ├── plugin.json
          └── skills/
              └── oncall-triage/
                  └── SKILL.md

marketplace.json:

{
  "name": "Acme internal marketplace",
  "description": "Plugins the platform team maintains for Acme engineers.",
  "plugins": [
    {
      "name": "acme-review",
      "source": "https://git.acme.example/platform/clarvis-marketplace.git",
      "path": "plugins/acme-review",
      "description": "Review checklists and a reviewer agent.",
      "homepage": "https://wiki.acme.example/clarvis/acme-review"
    },
    {
      "name": "acme-runbooks",
      "source": "https://git.acme.example/platform/clarvis-marketplace.git",
      "path": "plugins/acme-runbooks",
      "description": "On-call runbooks as skills."
    }
  ]
}

plugins/acme-review/plugin.json:

{
  "name": "acme-review",
  "version": "1.0.0",
  "description": "Review checklists and a reviewer agent.",
  "author": { "name": "Acme Platform", "email": "platform@acme.example" }
}

Installing `acme-review` clones the whole repository shallowly, keeps only `plugins/acme-review/`, and moves it to `~/.clarvis/plugins/acme-review/`. The rest of the checkout is deleted.

Pattern 02 Pointing Clarvis at the catalog, globally and per repository Configuration

You want your own machine to see the catalog everywhere, and you want the team repository to suggest it to whoever clones the repository.

Pointing Clarvis at the catalog, globally and per repository example

~/.clarvis/settings.json (yours, this is where the pointer belongs):

{
  "marketplaces": [
    "https://git.acme.example/platform/clarvis-marketplace.git"
  ],
  "enabledPlugins": [
    "acme-runbooks"
  ]
}

If you use SSH rather than HTTPS, either of these forms is accepted:

  "git@git.acme.example:platform/clarvis-marketplace.git"
  "ssh://git@git.acme.example/platform/clarvis-marketplace.git"

For a dry run before you push anything, point at a local checkout:

  "file:///home/you/work/clarvis-marketplace"

A repository can also suggest a catalog, in <your-repo>/.clarvis/settings.json:

{
  "marketplaces": [
    "https://git.acme.example/platform/clarvis-marketplace.git"
  ]
}

That entry does not take effect on its own. Open the repository and run `/doctor` to see the workspace trust row and what is being withheld, then run `/workspace-trust`, which approves immediately without a confirmation step and reports what became active. Until then Clarvis holds the field back from the merge and the Marketplace view behaves as if the repository had said nothing. If you later change the repository's `.clarvis/settings.json`, the approval no longer matches and the field is withheld again until you re-approve.

When both scopes contribute, the URLs are concatenated with global first, then workspace, and duplicates are dropped keeping the earlier position.

Verify the behavior

Check the boundary, not just the happy path.

Use a small disposable task first. Confirm what works and what is deliberately unavailable before relying on the configuration in a real workflow.

01
Clarvis can read marketplace.json from the repository root.
02
Each catalog name matches the plugin manifest reached by its source and optional path.
03
A newly installed plugin remains inactive until the user explicitly enables it.

Next guide

Connect organizational memory

Keep the agent-facing memory tools while choosing the knowledge system behind them.

Continue All guides