Share your setup with a team
CLAUDE.md was one developer’s memory. A team setup is configuration management: what everyone gets is committed, what is personal stays out, and the plugin is the unit of sharing.
01The goal
Share your Claude Code setup with a team: commit the settings everyone should get, keep your personal files out of git, and give the team a plugin that loads from a marketplace inside the repository — with no install command for anyone.
02The idea
| Committed — everyone gets it | Out of git — yours alone |
|---|---|
| .claude/settings.json | .claude/settings.local.json |
| CLAUDE.md | CLAUDE.local.md |
| .claude/rules/, skills, agents, .mcp.json | (anything with a key or a machine path) |
A plugin packages skills, agents and hooks as one unit, and a marketplace is just a folder whose .claude-plugin/marketplace.json lists plugins. Commit the marketplace inside the repository, register it in .claude/settings.json under extraKnownMarketplaces with a relative directory path, and turn the plugin on under enabledPlugins. Each teammate who accepts the workspace trust dialog for the folder gets the plugin — no install step, because a plugin listed by a relative path loads from the marketplace copy in place.
03The walkthrough
- 01Build a small marketplace by hand at team-marketplace/: a .claude-plugin/marketplace.json naming your marketplace (say team-tools) and listing one plugin by relative path (./plugins/team-kit), and under plugins/team-kit/ a .claude-plugin/plugin.json plus one skill — skills/onboard/SKILL.md that tells Claude to explain the repository’s shared setup without changing files — and, optionally, one read-only agent at agents/config-reviewer.md. Upstream ships exactly this kit as an example; link below.
- 02Validate both levels: claude plugin validate ./team-marketplace, then claude plugin validate ./team-marketplace/plugins/team-kit --strict. The marketplace check does not open the files of the plugins it lists — the second, strict run does.
- 03Register it in .claude/settings.json, beside your existing keys: "extraKnownMarketplaces": { "team-tools": { "source": { "source": "directory", "path": "./team-marketplace" } } } and "enabledPlugins": { "team-kit@team-tools": true }. The plugin’s id is always <entry name>@<marketplace name>.
- 04Commit both, and start a new session at the repository root, accepting the trust dialog. The plugin loads silently: /team-kit:onboard runs the skill, and typing @ offers team-kit:config-reviewer in the typeahead. If Claude asks to run a command along the way, check it only reads, then approve.
- 05Override for yourself only: set "team-kit@team-tools": false under enabledPlugins in .claude/settings.local.json and run /reload-plugins. The skill is gone from your session while the committed file still turns it on for everyone else — your local file outranks the project’s. Undo it the same way.
- 06Add .claude/settings.local.json and CLAUDE.local.md to .gitignore, and commit that too: a personal file that git tracks is a personal file everyone receives.
04Your turn
Move one real piece of your setup into the plugin — a skill your team should share, or a reviewer agent — so it lives at team-marketplace/plugins/team-kit/ and no longer under .claude/. Validate strictly, commit, and prove it in a new session: the component runs under the plugin’s name, with no install command. Remember the trade: an edit under team-marketplace/ takes effect at the next session start or after /reload-plugins, with no version bump.
Two sharing traps. A component left in both .claude/ and the plugin loads twice — both command names work, and a moved hook fires twice per event; finish the move. And treat the marketplace as code that runs with your teammates’ rights: a plugin’s hooks and MCP server processes run outside the sandbox, and permission rules do not cover the code they run. A change under team-marketplace/ gets the same review as any other change — on our board it would need exactly that.
Which file never belongs in a commit?
- A.claude/settings.local.json
- B.claude/settings.json
- C.mcp.json
→Check your answer
The local settings file is the personal override layer — committing it hands one person’s machine to everyone. CLAUDE.local.md is its memory-file twin.
Why does the plugin need no install command for teammates?
- AThe marketplace installs it on trust automatically
- BIt is listed by a relative path, so it loads from the marketplace copy in place
- CenabledPlugins copies it into ~/.claude at clone time
→Check your answer
A relative-path entry loads in place once the repository’s marketplace registration applies — which happens after the teammate accepts the trust dialog. External-source entries are the ones that still need an install.
A relative marketplace path resolves against…
- AThe session’s working directory, wherever it is
- BThe first session that opened the repo
- CThe repository’s main checkout — so worktree sessions share it
→Check your answer
Paths resolve against the main checkout, so every worktree shares one marketplace location — and a worktree session cannot load a plugin committed by another session until the merges land.