How to Share Claude Code Skills With Your Team

To share Claude Code skills with a team, commit them to the repository under .claude/skills/ so everyone who clones it gets them automatically, or, for skills used across many repositories, package them as a plugin in a marketplace that teammates add with /plugin marketplace add your-org/repo. Either way, treat skills like code: review changes in pull requests, assign owners, and version anything distributed beyond a single repo.

This guide covers both distribution paths, how to version skills, and a review process that keeps shared skills trustworthy.

Which sharing method fits your team?

Method	Setup	Reach	Updates	Best when
Project skills in git	None	One repository	git pull	Skills tied to one codebase
--add-dir skills repo	One clone per person	Any repo, opt-in per session	git pull in the skills repo	A small team sharing a few skills
Plugin and marketplace	A manifest file or two	Any repo, any person who installs it	Through /plugin	Many repos, versioned releases, bundled agents or hooks

Most teams start with project skills and move to a plugin once the same skill gets copied into a third repository.

Method 1: Commit project skills to git

Project skills live in .claude/skills/<name>/SKILL.md at the repo root. Anyone who opens Claude Code in the repo gets them, with nothing to install.

mkdir -p .claude/skills
curl -fsSL https://claudeskills.page/install.sh | sh -s -- code-review --project
git add .claude/skills/code-review
git commit -m "Add shared code-review skill"

A typical layout for an application repo:

.claude/
├── settings.json
└── skills/
    ├── code-review/          # adapted from the directory, with our rules
    ├── release-checklist/    # written in-house
    └── schema-migrations/    # installed from claudeskills.page

Things to get right:

• Adapt installed skills. A skill from a directory is a starting point. Add your conventions to code-review rather than keeping a separate document that says “also check X.”
• Pick distinctive names. A teammate’s personal skill with the same name takes precedence over the project skill on their machine. acme-release is safer than release.
• Use nested skills in monorepos. Skills in services/billing/.claude/skills/ load only when someone is working in that package.
• Reference repo scripts by path. Use ${CLAUDE_PROJECT_DIR}/scripts/... for repo scripts and ${CLAUDE_SKILL_DIR}/scripts/... for scripts bundled inside the skill.

Method 2: Share a skills repository with —add-dir

If a handful of people want the same skills across several repos but you do not want a plugin yet, keep them in one repository and attach it per session:

git clone [email protected]:acme/claude-skills.git ~/src/claude-skills
claude --add-dir ~/src/claude-skills

Claude Code loads skills from that directory’s .claude/skills/ folder and picks up edits live. It is lightweight, but it is opt-in per session and has no versioning beyond git history, so it does not scale much past a small group.

Method 3: Build a plugin and a marketplace

A plugin bundles skills with optional subagents, hooks, and MCP server configuration. A marketplace is a catalog that lists one or more plugins. Both can live in a single git repository.

Plugin structure

acme-claude/                          # marketplace repository
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── backend-toolkit/
        ├── .claude-plugin/
        │   └── plugin.json
        ├── skills/
        │   ├── schema-migrations/
        │   │   └── SKILL.md
        │   └── api-conventions/
        │       ├── SKILL.md
        │       └── references/
        ├── agents/
        │   └── security-reviewer.md
        └── hooks/

The plugin manifest names the plugin and carries its version:

{
  "name": "backend-toolkit",
  "version": "1.4.0",
  "description": "Migration safety, API conventions, and security review for Acme backend services"
}

The marketplace file lists the plugins and where to find them:

{
  "name": "acme",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "backend-toolkit",
      "source": "./plugins/backend-toolkit",
      "description": "Migration safety, API conventions, and security review"
    }
  ]
}

Check the official Claude Code documentation for the full plugin and marketplace schema; the fields above are the minimum most teams need. plugin-marketplace-publisher scaffolds and validates both files.

Installing from your marketplace

Teammates add the marketplace once, then install plugins from it:

/plugin marketplace add acme/acme-claude
/plugin install backend-toolkit@acme

marketplace add also takes a full git URL (including private repos the user can read), a local path, or a URL to a hosted marketplace.json. To install a plugin for everyone in a project from the command line:

claude plugin install backend-toolkit@acme --scope project

Projects can also declare the marketplace and the plugins they expect in .claude/settings.json, so the setup is part of the repository rather than a step in a README (see the official docs for current behavior):

{
  "extraKnownMarketplaces": {
    "acme": { "source": { "source": "github", "repo": "acme/acme-claude" } }
  },
  "enabledPlugins": { "backend-toolkit@acme": true }
}

Plugin skills are namespaced, so the migration skill above is invoked as /backend-toolkit:schema-migrations. It never collides with a personal or project skill of the same name, which removes the precedence confusion of Method 1.

How should you version shared skills?

Project skills are versioned by the repository; their history is the commit log. Anything distributed to multiple repos needs explicit versions.

• Bump version in plugin.json for every release, using semantic versioning. A wording tweak is a patch, a new skill is a minor version, and removing or renaming a skill is a major version, because it breaks anyone typing the old /name.
• Tag releases in git (v1.4.0) so you can see exactly what shipped.
• Optionally record a version in the skill itself with the open-standard metadata field. Values must be strings:

metadata:
  owner: platform-team
  version: "1.4.0"

• Keep a changelog that says what changed in behavior, not just in text. “migration-review now flags SET NOT NULL on tables over 1M rows” tells reviewers what to test.
• Announce updates. Third-party marketplaces do not auto-update by default, so people stay on old versions until they update through /plugin.

A review process for shared skills

A shared skill runs with every teammate’s permissions and shapes how Claude works on your code, so review it like code.

1. Assign owners

# .github/CODEOWNERS
/.claude/skills/schema-migrations/  @acme/database
/.claude/skills/release-checklist/  @acme/release-managers
/plugins/backend-toolkit/           @acme/platform

2. Use a pull request checklist

For every new or changed skill, reviewers check:

• name matches the folder; description says what and when
• Trigger tested: three prompts that should fire, two that should not, in fresh sessions
• Body under about 500 lines; detail moved to references/
• Every script read line by line: no network calls, credential access, or destructive commands that are not explained
• allowed-tools is as narrow as possible, with no bare Bash
• Every !`command` is read-only and handles failure
• Side-effecting skills (deploy, publish, notify) have disable-model-invocation: true
• No secrets, internal URLs, or personal paths

3. Validate in CI

A small check catches the mechanical errors before review:

#!/usr/bin/env bash
# ci/check-skills.sh
set -euo pipefail
status=0
for f in .claude/skills/*/SKILL.md plugins/*/skills/*/SKILL.md; do
  [ -f "$f" ] || continue
  dir=$(basename "$(dirname "$f")")
  python3 - "$f" "$dir" <<'PY' || status=1
import sys, re, yaml
path, folder = sys.argv[1], sys.argv[2]
fm = yaml.safe_load(open(path).read().split('---')[1])
name, desc = fm.get('name', ''), fm.get('description', '')
errs = []
if name != folder: errs.append(f'name "{name}" != folder "{folder}"')
if not re.fullmatch(r'[a-z0-9]+(-[a-z0-9]+)*', name or '') or len(name) > 64: errs.append('invalid name')
if not 1 <= len(desc) <= 1024: errs.append('description length')
lines = open(path).read().count('\n')
if lines > 500: errs.append(f'{lines} lines; move detail to references/')
for e in errs: print(f'{path}: {e}')
sys.exit(1 if errs else 0)
PY
done
exit $status

4. Review third-party skills before adopting them

When someone proposes adding a skill from a directory, including this one, the reviewer reads the full SKILL.md and every bundled file before merging. Each skill page on claudeskills.page shows all files for exactly this reason. The skill safety guide lists the red flags.

Keeping shared skills healthy

• Prune. Every installed skill adds its description to every session. Remove skills nobody uses.
• Avoid overlap. Two skills that both claim “review this PR” will compete. Merge them or make their descriptions mutually exclusive.
• Collect feedback. When a skill misfires, ask for the prompt that caused it. That prompt is your next test case.
• Watch for drift. If the procedure changes, the skill must change in the same PR. A stale skill is worse than none, because Claude follows it confidently.

Next steps

• Choose the right location: Personal vs project skills
• Write skills worth sharing: Skill authoring best practices
• Audit before you adopt: Are Claude Code skills safe?
• Helpful skills: plugin-marketplace-publisher, permissions-policy, memory-file-architect