Someone writes a useful skill, it lives on their machine, and two weeks later a colleague solves the same problem from scratch. That is the pattern most teams fall into.

The previous post covered how to write skills for Claude Code: a SKILL.md file that teaches Claude a workflow, living in your home directory where it applies to every project you work on. That setup works well for personal workflows. It breaks down the moment you want someone else to benefit from what you figured out. This post covers the next layer: plugins, marketplaces, and keeping shared skills alive as the team grows.

Committing skills to the repo

Project-scoped skills work by committing a .claude/skills/ directory to the repo. Everyone who clones it gets the skill. That is the right starting point for project-specific knowledge: deployment procedures, PR conventions, how to run the integration tests. A monorepo makes this even simpler: one shared .claude/skills/ directory at the repo root and you are done. For skills that span multiple projects, you need the next layer.

Packaging skills as plugins

Skills can live in three places: your home directory for personal use, a project repo for team-specific knowledge, or a plugin for anything that needs to follow a developer across multiple projects.

A plugin is a directory with a plugin.json manifest that groups related skills into a single installable unit. Install the plugin, you get everything in it. That is the main reason grouping matters: put the wrong skills together and everyone who installs gets capabilities they did not ask for.

Plugins can also bundle slash commands, subagents, MCP server configurations, and hooks, though you can start with just skills.

A dev-tools plugin containing three everyday development skills looks like this:

dev-tools/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── review-pr/
    │   └── SKILL.md
    ├── write-tests/
    │   └── SKILL.md
    └── explain-code/
        └── SKILL.md

{
  "name": "dev-tools",
  "version": "1.0.0",
  "description": "Everyday development workflows"
}

The manifest is optional since Claude Code auto-discovers skills in a ./skills/ directory, but the version field matters a lot once you start distributing plugins to other people (see “The versioning gotcha” below).

How to decide what goes in a plugin

Group by who installs it. A developer writing application code has different needs from someone on the platform team, and that gap is a trust boundary too. An infrastructure plugin containing a provision-infra skill should not be installed on every developer’s machine. Provisioning cloud resources has side effects, and that capability belongs with the platform team, not every engineer’s Claude session. A dev-tools plugin with skills like review-pr, write-tests, and explain-code is safe for everyone. A separate security plugin for dependency auditing and secret scanning can be scoped to whoever owns that review process.

Someone without platform access should not have a provision-infra skill in their Claude session, even unused. Separating by plugin makes the access decision explicit: you install what you need.

Within a plugin, lean toward grouping skills that always travel together. If a developer who wants review-pr would always want write-tests as well, they belong in the same plugin. If two skills are only occasionally used together or target different roles, separate plugins give each team the option to install only what applies to them.

Distributing plugins with a marketplace

A marketplace is a Git repository containing a marketplace.json file that catalogs what plugins are available and where to find them.

acme-corp/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    ├── dev-tools/
    │   ├── .claude-plugin/plugin.json
    │   └── skills/
    │       ├── review-pr/SKILL.md
    │       └── write-tests/SKILL.md
    └── infrastructure/
        ├── .claude-plugin/plugin.json
        └── skills/
            ├── provision-infra/SKILL.md
            └── check-logs/SKILL.md

{
  "name": "acme-marketplace",
  "owner": { "name": "DevTools Team" },
  "plugins": [
    {
      "name": "dev-tools",
      "source": "./plugins/dev-tools",
      "description": "Standard development workflows"
    },
    {
      "name": "infrastructure",
      "source": "./plugins/infrastructure",
      "description": "Platform team skills: infrastructure provisioning and log access"
    }
  ]
}

A team member adds the marketplace once, then installs plugins from it:

claude plugin marketplace add acme-corp/claude-plugins
/plugin install dev-tools@acme-marketplace

They can also browse all available plugins interactively with /plugin.

Private repos and data access

Most teams will not want their skills in a public repository. The marketplace source supports private GitHub and GitLab repos, using the Git credentials already on the developer’s machine. If you can clone the repo, you can install from it.

If the repo is private, only developers with access to acme-corp/claude-plugins can fetch the marketplace index or install plugins from it. Someone without access who obtained the settings.json file would hit an authentication wall when Claude Code tried to resolve the source.

Your skill files sit in your private repository. Anthropic cannot see them there. But once Claude invokes a skill during a session, the content loads into the context window and goes to Anthropic’s API. That is true of any file Claude reads in a conversation. Review skills that contain proprietary workflows, internal system names, or credentials before distributing them.

Making the marketplace automatic

Manual installation still requires people to know the marketplace exists. The better approach is to add it to the project’s .claude/settings.json and commit that file:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "dev-tools@acme-tools": true
  }
}

When a team member opens the project and trusts the folder (Claude Code’s permission prompt when opening a new project directory), Claude Code registers the marketplace and prompts to install the listed plugins. They can skip any they do not want, but they do not need to track down the marketplace themselves.

This settings file is also a shared lock file for plugin versions. When you ship a new version of a plugin, bump the version in plugin.json, commit, and push. The next time a team member opens a project with this settings file, Claude Code notices the version mismatch and prompts them to update.

The versioning gotcha

Claude Code caches installed plugins locally in ~/.claude/plugins/cache/. If you update a skill but do not bump the version in plugin.json, users get the old behavior with no warning. This is the most common reason a skill stops working after a change.

Bump the version on every change, including small ones like wording improvements. Plugin versioning follows semantic versioning: patch for typos and prompt tweaks, minor for new skills, major when behavior changes in a way that could break something that was working.

Treat changes to shared skills like changes to shared code: they should go through review before merging.

A CHANGELOG.md per plugin is easy to maintain and is the first thing to check when a skill behaves unexpectedly.

For significant changes, announcing in a developer channel is more reliable than expecting people to run the update command. A short note like the following is enough:

dev-tools 1.3.0 is out — new /write-tests skill. Run /plugin update dev-tools@acme-tools to update.

Users who need to check their installed version can find it at /plugin under My Plugins.

Plugin skills as shared code

Shared code that breaks usually fails loudly: tests catch it, the build fails, someone gets a notification. Shared skills fail silently. Claude still responds, just differently than before, with no error to surface the change. That asymmetry is why shared plugin skills need the same discipline as shared libraries: review before changes ship, a changelog, and a version bump on every release.

Getting started

Commit a .claude/skills/ directory to the project repo first. Write one skill for something your team does repeatedly. If people use it, build the marketplace. If they do not, you have lost nothing and gained some documentation.

Skills go stale when nobody owns them. Workflows change, tools get replaced, and the skill keeps giving outdated guidance. Before you distribute shared skills, settle the question of who is responsible for keeping them accurate. Everything else follows from that.

References