A shared kit for the team

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

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:

{
  "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

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:

{
  "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:

{ "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.