Team Claude: Sharing Configuration Across People and Machines

The issue: Claude Code personalisation is often thought of as a solo practice — your CLAUDE.md, your skills, your setup. But the project-level layer of that setup can be shared across a team through git, and doing so embeds shared methodological conventions directly into every team member's Claude environment. This is one of the least-known and most practically useful properties of the system.

The fundamental split: personal vs. shareable

Not everything in a Claude setup can or should be shared. The split follows a simple rule: anything in ~/.claude/ is personal; anything in the project folder can be shared via git.

PERSONAL (never commit, never share)
  ~/.claude/
    CLAUDE.md              ← who you are, your preferences
    MEMORY.md              ← facts Claude has learned about you
    commands/              ← your personal global skills
    settings.json          ← your default permissions

SHAREABLE (in the project folder, in git)
  your-project/
    CLAUDE.md              ← project context and conventions
    .claude/
      commands/            ← team skills
      settings.json        ← agreed team permissions
    _history.md            ← project narrative
    _ownership.md          ← attribution record
    notes/progress.md      ← current task state

NOT SHAREABLE (in the project folder, NOT in git)
  your-project/
    .claude/
      settings.local.json  ← your personal overrides, local paths, tokens

The .local.json convention signals "do not commit": this file holds personal API tokens, local file paths, and machine-specific overrides that would break or expose things if shared. It is gitignored by default. The non-local settings.json can be committed.

What a team gets from git

When someone clones a project repository that has been set up with team Claude configuration, they receive automatically:

CLAUDE.md — the project context: what the project is, the folder structure, the conventions, the terminology. Every team member's Claude knows the project from the moment they clone and launch.

.claude/commands/ — the team's shared skills. An /extract-persons prompt developed and refined by one researcher is immediately available to all. Methodological decisions encoded in a skill prompt — how to handle uncertain attributions, what fields to extract, how to mark gaps — are shared without anyone having to copy-paste or communicate them separately.

.claude/settings.json — agreed team permissions. If the team has decided that web search and certain bash commands should be auto-allowed in this project, that configuration propagates to every team member.

Accountability files — _history.md, _ownership.md, notes/progress.md. A new team member reads the history and immediately understands not just the current state but how it was reached, what was tried and abandoned, and what the open questions are.

What they do not receive — and must set up themselves — is the personal global layer: their own ~/.claude/CLAUDE.md (who they are, their personal preferences), their personal global skills, and their personal settings.

The team baseline: what to commit

CLAUDE.md as a team document

A project CLAUDE.md committed to git is a team document, not a personal one. It should contain:

It should not contain personal preferences like response length or tone — those belong in individual global CLAUDE.mds. When someone edits a committed CLAUDE.md, they are editing the shared methodology, not their personal setup.

.claude/commands/ as shared methodology

Skills committed to .claude/commands/ are the most direct way to share methodological conventions as executable logic.

Example: A team working on medieval register extraction has developed a precise /extract-persons skill after iterating on it across 50 sources. Every edge case they have encountered — how to handle name variants, uncertain dates, references to unnamed individuals — is encoded in the prompt. When a new team member joins:

  1. They clone the repository
  2. Launch Claude from the project folder
  3. /extract-persons is immediately available, with all accumulated refinements

No manual transmission of methodology. No risk of someone using an outdated version of the prompt. The skill is the convention.

The evolution pattern: Skills in git have a history. You can see when the extraction prompt changed, what changed, and why — just like any other file. If a change produces worse results, you can roll it back. The skill evolves with shared understanding, not with whoever happens to remember the latest version.

.claude/settings.json as team permissions

The non-local settings file can specify tool permissions that apply to everyone working on the project:

{
  "permissions": {
    "allow": [
      "WebSearch",
      "WebFetch",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm *)"
    ]
  }
}

This is useful when a team has agreed that certain tools should be auto-allowed (reducing interruptions) and certain operations should be blocked at the project level (protecting data). Each team member can add personal overrides in their settings.local.json.

What goes in .gitignore

A project using Claude Code should add the local settings file to .gitignore:

.claude/settings.local.json

If you are also keeping other personal files in the project folder that should not be shared — drafts, personal notes, local data exports — add those too.

The accountability files (_history.md, _ownership.md, progress.md) should be committed. They are shared project records, not personal files.

Onboarding a new team member

With a properly configured repository, onboarding is:

  1. Clone the repo — they get CLAUDE.md, shared skills, team settings, all accountability files
  2. Set up their personal global layer (if they haven't already) — ~/.claude/CLAUDE.md with their identity and preferences
  3. Create their local settings file — .claude/settings.local.json with any personal overrides and their personal MCP tokens
  4. Read the project history — > Read _history.md. Give me a summary of the project and where it currently stands.

That last step is not a Claude Code mechanism — it is a prompt. But it is the most powerful onboarding tool the team has: a new collaborator can get genuinely up to speed on months of work in one conversation.

Moving your personal setup to a new machine

The personal layer lives in ~/.claude/. Moving it is straightforward:

Copy the folder:

# On old machine: create an archive
tar -czf claude-config.tar.gz ~/.claude/

# Transfer to new machine (USB, cloud, etc.)

# On new machine: unpack
tar -xzf claude-config.tar.gz -C ~/

Or just copy the files manually — ~/.claude/CLAUDE.md, ~/.claude/MEMORY.md, and ~/.claude/commands/ are plain text files. Open them on the old machine, copy, paste into new files on the new machine.

Project-level configuration comes with the repository — git clone on the new machine and the project layer is already there.

The personal/shared tension

The most common mistake in team Claude setups is putting personal preferences in the shared CLAUDE.md. When one team member's preference for concise responses, or their citation style, ends up in the project CLAUDE.md, everyone else's Claude inherits it.

The rule: Project CLAUDE.md contains what is true about the project. Personal ~/.claude/CLAUDE.md contains what is true about you. When something belongs in one and ends up in the other, it either:

A second tension: skills that belong globally vs. skills that belong to the team. A /to-md conversion skill is useful everywhere — it belongs in ~/.claude/commands/. An /extract-persons skill tuned to this project's sources belongs in .claude/commands/. Putting the former in the latter means it disappears in other projects. Putting the latter in the former means everyone gets a project-specific prompt in contexts where it does not make sense.

A realistic team setup

repository/
  CLAUDE.md                    ← project context, conventions, folder rules
  .gitignore                   ← includes .claude/settings.local.json
  _history.md                  ← decisions and project narrative (committed)
  _ownership.md                ← attribution record (committed)
  notes/
    progress.md                ← current task state (committed)
  .claude/
    commands/
      extract-persons.md       ← shared extraction methodology
      add-to-log.md            ← shared log-entry skill
      check-output.md          ← shared QA routine
    settings.json              ← agreed team permissions (committed)
    settings.local.json        ← each person's local overrides (gitignored)
  sources/                     ← primary sources (do not modify)
  output/                      ← extracted data

Each team member also has, on their own machine:

~/.claude/
  CLAUDE.md                    ← who they are, personal preferences
  MEMORY.md                    ← what Claude has learned about them
  commands/
    to-md.md                   ← personal global skills
    summarise.md

The two layers combine. The project layer is shared and version-controlled. The personal layer is individual and never leaves the machine.

Related