Building a team-shared skill library that doesn't decay in six months

Published 2026-05-11 by Owner

The first three months after a team adopts Claude Code look the same everywhere: three engineers independently write a code-review skill, two of them write a deploy skill that does nearly the same thing, and someone on the platform team builds a database-migration skill that no one else knows exists. Six months later, half those skills are stale, a quarter are duplicates of each other, and the engineer who wrote the good migration skill has left the company.

This is the default trajectory. It’s not negligence — it’s what happens when a team-wide capability is treated as a personal productivity tool by each individual. Skills are just YAML-and-markdown files; they feel personal. They accumulate in ~/.claude/skills/ without review, without versioning, without anyone responsible for them.

The fix is straightforward: treat the team’s skill library like you treat shared library code. Check it into git, review additions, and have a path for retiring things that no longer apply.

Why “everyone has their own skills folder” fails

Individuals naturally build skills that solve their immediate problem. That’s good. The breakdown happens at the next layer up.

Duplication is invisible. When each person’s skills live in a personal directory, there’s no way to know what the person sitting next to you has built. Teams routinely end up with four variations of a similar skill — different prompts, different quality, no way to tell which one to use.

No shared mental model. If two engineers mention “the review skill” in a meeting, they might be referring to different prompts entirely. The same name means different things to different people. This is the point at which team communication starts to fracture: you can’t build shared vocabulary around tools that don’t have a shared canonical form.

Knowledge leaves with people. The engineer who wrote the best skill for working with your internal API knows its quirks in a way that took months to accumulate. That knowledge is encoded in the skill’s prompt. When they leave and their dotfiles go with them, the skill is gone. If it was in git it wouldn’t be.

Valuable patterns stop evolving. A personal skill doesn’t get better from feedback. A shared skill that ten engineers use will surface problems and improvements within a week.

Repo structure for a shared skill library

There are two options depending on how your team uses Claude Code.

Option 1: .claude/skills/ in the project repo. For skills that are project-specific — skills that know about your architecture, your internal APIs, your codebase conventions — the right home is .claude/skills/ at the project root. Checked into git alongside your code, reviewed with the same process, readable by everyone who clones the repo.

.claude/
├── skills/
│   ├── review.md
│   ├── ship.md
│   ├── db-migration.md
│   ├── rfc-draft.md
│   └── deprecated-deploy-v1.md
└── settings.json

The advantage: new team members get every skill automatically when they clone. The skills version-control alongside the code they’re designed for. When you refactor the deploy pipeline, you update the ship.md skill in the same PR.

Option 2: A standalone skills repo. For teams with multiple repos, or for skills that apply across projects (onboarding, retros, general code review), a separate repo that everyone installs is cleaner.

company-claude-skills/
├── skills/
│   ├── review.md
│   ├── incident-postmortem.md
│   ├── rfc-draft.md
│   └── deprecated-standup-summary.md
├── install.sh          ← symlinks into ~/.claude/skills/
└── CLAUDE.md           ← documents what each skill is for

The install script is a one-liner: ln -sf "$(pwd)/skills" ~/.claude/skills/company. Engineers add the repo as a git submodule or just clone it. The downside is that team members need to pull updates manually, or you need a cron job to do it.

The tradeoff in one sentence: project-repo skills are better for project-specific knowledge; standalone repos are better for cross-cutting team practices. Most teams end up with both.

Naming conventions and the description-review process

The worst naming problem on shared skill libraries is ambiguity: review.md and code-review.md coexist, no one knows which is canonical, both are used, both drift.

The convention that works is team-prefix-* namespacing when there’s any risk of collision with personal or external skills:

acme-review.md
acme-ship.md
acme-db-migration.md
acme-rfc-draft.md

For project-scoped skills where there’s no collision risk, the prefix isn’t necessary. The goal is that the name is unambiguous, not that it carries the company brand on every invocation.

Descriptions get reviewed like code. The frontmatter description field in a skill file is the primary way engineers decide whether to use a skill. A vague description — “helps with code stuff” — means the skill won’t get used. A specific description — “Reviews a PR branch diff for issues; expects a branch name or GitHub PR URL” — tells you exactly when to reach for it.

Treat description quality as a review criterion. When someone opens a PR to add a skill, the description is the most important line. If the reviewer can’t tell from the description alone when to use the skill and what it expects as input, the description needs to be rewritten before the PR merges.

This also catches duplicate submissions early. A reviewer who sees “generates a database migration script from a schema diff” in a new skill’s description will catch that acme-db-migration.md already exists and the new skill should either replace it or be given a meaningfully distinct name.

Trigger language matters. Skills in Claude Code can include trigger keywords that activate them. The shared library should standardize on / commands (/acme-review, /acme-ship) so muscle memory transfers between engineers. If one person invokes via natural language and another via slash command, the shared library isn’t actually shared — it’s the same files being used differently.

The skill-deprecation lifecycle

Deleting a skill immediately is the wrong move. Engineers have that skill name in their notes, in their CLAUDE.md, in their Slack messages. Removing it breaks their workflow without warning.

The lifecycle:

1. Rename with deprecated- prefix. When a skill is superseded or no longer useful, rename it from acme-deploy-v1.md to deprecated-acme-deploy-v1.md. Update the description to read: “DEPRECATED — use /acme-ship instead. Will be removed after [date].” This is the “keep for a sprint” window. The skill still works; it just announces its own obsolescence.

2. Update CLAUDE.md. The project’s CLAUDE.md should remove the old skill from its index and add the new one in the same PR that renames the skill. Anyone who reads CLAUDE.md before reaching for a skill — and they should — will be pointed at the right one.

3. Remove after the window. One sprint is usually enough. If anyone’s still using the deprecated skill after two weeks, they’ll find out and update. The removal PR is a one-liner.

The pattern works because it converts a hard cutover into a gradual handoff. The deprecated- prefix is visible in file listings, in autocomplete, and in any grep of the skills directory. It’s not subtle.

One thing to avoid: adding a deprecation comment inside the skill file without renaming it. Engineers find skills by filename. A skill named deploy.md that contains a deprecation notice will keep getting used by people who don’t read the contents before invoking.

CLAUDE.md as the skill index

The project’s CLAUDE.md is where new contributors go to understand how Claude Code is used on this project. That makes it the natural home for the skill index.

A pattern that works:

## Claude Code skills

For common tasks, use these skills rather than writing your own prompts:

- `/acme-review` — code review on the current branch diff; runs style, logic,
  and security checks against our internal guidelines
- `/acme-ship` — runs tests, opens a PR, requests reviewers from CODEOWNERS
- `/acme-db-migration` — generates a migration script from a schema-diff
  argument; expects Postgres syntax
- `/acme-rfc-draft` — scaffolds an RFC document from a problem statement

For onboarding, run `/acme-review` on your first PR and compare its output
to what the human reviewer says. That delta tells you what the skill doesn't
know about our codebase yet.

This is three things at once: documentation for new contributors, a quick-reference for existing ones, and a forcing function for the team to keep the index current. When a skill is added to the library, CLAUDE.md gets updated in the same PR. When a skill is deprecated, the entry is removed.

The last paragraph in the example above — using /acme-review on a first PR as a calibration exercise — is the kind of earned process note that makes a CLAUDE.md useful rather than just a list. The skill index is more valuable when it tells contributors not just what exists but how to fit it into their workflow.

A few things that belong in the skill index but often get omitted:

What the skill expects as input. “Run /acme-db-migration against your schema diff” is only useful if contributors know how to produce a schema diff and pass it. The CLAUDE.md entry should include the simplest invocation example that actually works.

What the skill doesn’t do. The /acme-review skill at most teams reviews the current branch’s diff. It doesn’t catch issues in unchanged code that new code now interacts with. Saying that in the index prevents contributors from filing “why didn’t the skill catch this” reports.

Who to talk to for a skill that doesn’t exist yet. If the team has a designated person for skill maintenance — or a Slack channel — the index should say so. This keeps skill requests from disappearing into the void and creates a path for surfacing gaps.

What this costs and when it’s worth it

The overhead is real. Adding a skill to the shared library takes longer than adding a personal skill. The PR review, the description discussion, the CLAUDE.md update — that’s probably 20-30 minutes of extra process per skill.

The break-even is roughly three engineers. If three people would otherwise each write the same skill independently, the shared library saves time on the second and third build, the reconciliation when they discover the duplication, and every future update. Below three engineers, the overhead might not be worth it; at five or more it almost certainly is.

The asymmetric case is knowledge preservation. A skill that one engineer builds and five others rely on is worth the overhead regardless of headcount, because the cost of losing it when that engineer leaves is larger than the cost of proper governance.

Teams that treat skills as throwaway personal tooling are betting that the engineers who built valuable knowledge into those skills will stay. Most teams lose that bet eventually. The shared library is the hedge.

The deeper shift is that a well-maintained skill library makes the team’s use of Claude Code visible. Invisible tools don’t get better. When the whole team can see what skills exist, what they’re for, and what’s been deprecated, they can have a conversation about what’s missing — and build toward it deliberately instead of by accident.

The next phase for most teams is making the skill library itself a target for improvement. Once skills are shared and visible, you can measure which ones get used and which don’t. A skill that no one invokes after two months is either solving the wrong problem or solving the right problem badly. Shared, version-controlled, and indexed, it’s fixable. Personal and invisible, it just quietly stops being used and then disappears the next time someone cleans up their dotfiles.