# A shared kit for the team

Course: Claude Code: Pro Level — https://zero2vibecode.com/learn/claude-code-pro
Canonical URL: https://zero2vibecode.com/learn/claude-code-pro/5-3-team-marketplace
Verified against: Claude Code v2.1.292 (2026-10-15)
Last updated: 2026-10-15

What everyone needs is committed to the repository; what is yours stays out of git. A marketplace right in the repository plus two keys in .claude/settings.json give everyone who clones the project and trusts the folder a shared plugin without a single install command.

Over the last levels you built your own setup: permission rules, hooks, skills, subagents. Now you need to hand it to the team — so that everyone gets the same thing, while your personal settings stay yours.

## What to commit and what not to

| Committed — for everyone | Stays with you |
|---|---|
| `.claude/settings.json` | `.claude/settings.local.json` |
| `CLAUDE.md` and `.claude/rules/` | `CLAUDE.local.md` |
| skills, agents, `.mcp.json` | |

The local settings file wins over the shared one: a teammate can override a team setting for themselves without a commit. The exception is lists such as permission rules: they are not replaced but merged.

Add both personal files to the project's `.gitignore` yourself. The rule Claude Code writes for `settings.local.json` goes into your global git ignore list — your teammates do not have it. And `CLAUDE.local.md` is created by hand, so keeping it out of git is on you too.

## A marketplace in the repository

A plugin packages skills, agents and hooks into one unit. A marketplace is a folder where a `.claude-plugin/marketplace.json` file lists plugins. You can put one right in the repository:

```
team-marketplace/
  .claude-plugin/marketplace.json     ← the team-tools marketplace
  plugins/team-kit/
    .claude-plugin/plugin.json        ← the team-kit plugin
    skills/onboard/SKILL.md
    agents/config-reviewer.md
```

In `marketplace.json`, the plugin is given by a relative path:

```json
{
  "name": "team-tools",
  "owner": { "name": "The team" },
  "plugins": [
    { "name": "team-kit", "source": "./plugins/team-kit" }
  ]
}
```

The entry's name (`team-kit`) must match `name` in the plugin's `plugin.json`.

## Checking before you commit

```bash
claude plugin validate ./team-marketplace
claude plugin validate ./team-marketplace/plugins/team-kit --strict
```

You need **both** runs. Validating the marketplace checks its file and entries, but does not open the skills and agents inside the plugins. The second run opens them, and `--strict` turns warnings into errors. Success ends with the line `Validation passed`.

## Two keys in the settings

In `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": { "source": "directory", "path": "./team-marketplace" }
    }
  },
  "enabledPlugins": {
    "team-kit@team-tools": true
  }
}
```

- the key inside `extraKnownMarketplaces` is the marketplace's `name`;
- the plugin's identifier is `entry-name@marketplace-name`;
- the value is `true`, not the string `"true"`;
- the relative path is resolved from the main copy of the repository, so a session in a worktree uses the same `team-marketplace/`.

Commit `team-marketplace/` and `.claude/settings.json`. A teammate clones the repository, runs `claude`, accepts the trust dialog — and the plugin loads **with no install command**. The skill is invoked as `/team-kit:onboard`, the subagent as `team-kit:config-reviewer`.

A plugin from a folder on disk loads in place: an edit in `team-marketplace/` is picked up at the next start or after `/reload-plugins`, with no need to bump the version number.

## For yourself

**Turn the shared plugin off just for you.** In `.claude/settings.local.json`:

```json
{ "enabledPlugins": { "team-kit@team-tools": false } }
```

Then `/reload-plugins`. For everyone else the plugin stays on.

**Try it without connecting it.** `claude --plugin-dir ./team-marketplace/plugins/team-kit` loads the plugin for one session and writes nothing to the settings.

## Pitfalls

- **Trust.** A marketplace from the repository silently waits until the person accepts the folder trust dialog. `claude -p` connects it only in a folder that was already trusted in an interactive session. A cloud session shows no dialog — such a marketplace never connects there. Shared permission rules wait for the same dialog.
- **Duplicates.** A component left in both `.claude/` and the plugin loads twice: both `/tdd` and `/team-kit:tdd` will work, and a hook will fire twice.
- **The name is forever.** A plugin is enabled as `name@marketplace`. A renamed plugin is a **different** plugin for everyone who had it enabled. If you need a new label, change `displayName`, not `name`.

**Careful.** 
Everyone who trusts the repository runs team-kit's contents with their own permissions. A plugin's hooks and MCP servers run outside the sandbox, and permission rules do not cover the code they run. Review changes to team-marketplace as carefully as code.

**Practice in the terminal.** Create .claude/settings.json with one echo command holding the extraKnownMarketplaces and enabledPlugins keys, then append the lines .claude/settings.local.json and CLAUDE.local.md to .gitignore. Check the result with cat.

**Try it on a real marketplace.** 
[claude-kit](https://github.com/FunFactoryDev/claude-kit) is our plugin marketplace for Claude Code. en-kit brings the five-whys, tdd, review-diff and claude-md-review skills plus a read-only code-reviewer agent; en-guard is a hook that keeps Claude from editing .env files and lockfiles; en-notify shows a desktop notification when Claude Code is waiting for you. Add it with `/plugin marketplace add FunFactoryDev/claude-kit`, then install with `/plugin install en-kit@claude-kit`. To practice with the real Claude Code on a real project, the [Claude Code practicum](https://github.com/FunFactoryDev/claude-code-practicum) has 14 tasks that `npm run check` grades for you.