Build a team skill library that stays sharp

Most teams start sharing Claude Code skills the same way: someone commits a folder, a few people add their own, and six months later nobody knows which skills fire, which ones help, or who owns them. This guide is for tech leads and senior developers who want one shared library that the whole team trusts. At the end you will have a versioned skill library in your repository, a test suite that proves each skill makes Claude better, and a short monthly routine that keeps the library small and accurate.

What you will have at the end

• A skill library in .claude/skills/team/ that loads for everyone who clones the repository, with skills called as /team:<name>.
• Four working skill templates: a task skill with live context, a file-scoped reference skill, a manual-only release skill and a forked research skill.
• Descriptions written to route, so Claude loads the right skill from natural phrasing and leaves it alone otherwise.
• An eval suite that runs every skill with and without the library and reports the difference, plus a CI script that fails the build when a skill regresses.
• An eval checklist and a monthly review that removes skills nobody uses.

Before you start

• Claude Code v2.1.269 or later, because that is the minimum for claude plugin eval. Check with claude --version and upgrade with claude update.
• Git 2.31 or later if git is installed, since older git makes the eval command stop before any case runs.
• A repository your team already uses with Claude Code, and permission to commit to it.
• Comfort with skill basics. If SKILL.md and frontmatter are new to you, read Your first skill in 10 minutes first.
• The attachment for this guide, skill-library-pack. Every file named below is in it, with YOUR_... placeholders where your team's details go.

A note on cost before you begin: every eval run and every judge grader is a real model call on your account. The suite in this guide is small on purpose.

Step 1: Give the library one home and one name

Copy the team/ folder from the pack to the root of your repository so the layout looks like this:

your-repo/
└── .claude/
    └── skills/
        └── team/
            ├── .claude-plugin/
            │   └── plugin.json
            ├── skills/
            │   ├── reviewing-changes/SKILL.md
            │   ├── writing-migrations/SKILL.md
            │   ├── writing-migrations/reference.md
            │   ├── releasing/SKILL.md
            │   └── researching-code/SKILL.md
            └── evals/

The manifest is four fields:

{
  "name": "team",
  "description": "YOUR_TEAM_NAME shared skill library. Owned by YOUR_OWNER_HANDLE.",
  "version": "1.0.0",
  "author": {
    "name": "YOUR_TEAM_NAME"
  }
}

Then check it before anything else runs:

claude plugin validate .claude/skills/team

You want to see ✔ Validation passed. The command checks the manifest and the frontmatter of every skill, agent and command file, so a typo in any SKILL.md shows up here instead of as a skill that silently never triggers.

Why this layout and not a flat set of folders in .claude/skills/? A plain project skill works fine for one or two skills. A library needs three things a flat folder does not give you.

First, a namespace. A folder in .claude/skills/ that contains .claude-plugin/plugin.json is a skills-directory plugin, and the plugin name becomes the prefix on every skill it holds. Your release skill becomes /team:releasing, so it can never collide with a teammate's personal releasing skill or a bundled command. Plain skills with the same name follow a precedence order in which personal beats project, which is exactly the kind of surprise you do not want in a shared library.

Second, distribution with no install step. To share a plugin through a repository, you can place it under .claude/skills/, and everyone who clones the repository gets it. Because the content comes from the repository, it loads only after the workspace trust check, so each teammate accepts the trust prompt once.

Third, tests. claude plugin eval needs a plugin directory with a manifest, and a skills-directory plugin qualifies. Plain project skills have no manifest, so for those the docs describe a manual baseline where you turn the skill off with skillOverrides and compare runs. The plugin layout gets the automated comparison, and step 5 depends on it.

One rule for the team: start Claude Code from the repository root. A plugin in .claude/skills/ loads from the session's primary working directory, and unlike plain skills, Claude Code does not search parent directories for it.

Open a session at the root, accept the trust prompt, run /reload-plugins, and type /team:. The four skills should appear. That is a working shared library. The rest of this guide makes it good and keeps it good.