Sharing and versioning skills across repos

A skill that lives in one repo helps one team. The same skill shared across repos, with real versioning, is what turns a good idea into infrastructure — and the mechanics for doing that already exist, they're just underused.

The three levels, and how conflicts resolve

Claude Code resolves skills from four sources: enterprise (managed settings, admin-controlled), personal (~/.claude/skills/, all your projects), project (.claude/skills/, this repo only), and plugin (<plugin>/skills/, wherever the plugin is enabled). When names collide, enterprise overrides personal, and personal overrides project; plugin skills are namespaced as plugin-name:skill-name so they never collide with the others (Use Skills in Claude Code). This matters for sharing: a skill you want every repo to use belongs at the enterprise or plugin level, not copy-pasted into each project's .claude/skills/.

One shared source, not N copies

The practical pattern is a dedicated skills repository packaged as a plugin, installed into each project via a plugin marketplace. A symlink from a project's .claude/skills/<name> to a shared checkout also works — Claude Code follows the symlink and reads SKILL.md from the target, and if the same skill is reachable from more than one location it's loaded once, not duplicated (Claude Code docs, plugins reference). Either way, the fix lands in one file, and every repo that references it picks it up on their next update — not on someone remembering to copy the change three more times.

Pinning versions

Plugins resolve their version from the plugin.json manifest first, falling back to the marketplace entry. You can tag a release with claude plugin tag, and a consuming repo can constrain to a semver range in its dependencies, such as "version": "~2.1.0" to accept patch updates but not the next minor version (Claude Code plugins reference). This gives you the same guarantee a package manager gives you for code dependencies: repo A can stay on v1.0 of the skill while repo B tries v2.0, and neither breaks the other.

Reviewing skill changes like code

Because a project-level skill lives in .claude/skills/ and a plugin skill lives in a git-tracked plugin repo, every change to a skill's instructions shows up as a diff. Treat that diff like you'd treat a change to a shared library: review what checklist item was added or removed, and run claude plugin validate --strict before merging, which validates a plugin's manifest, hooks, skills, and agents ahead of deployment (Claude Code plugins reference). A skill change that quietly drops a check is exactly the kind of thing code review is for.

Try it today

1. Identify one skill currently duplicated across two or more repos.
2. Move it into a dedicated skills repo (or a single canonical location) and package it as a plugin.
3. Tag a version (claude plugin tag) so consuming repos can pin rather than always tracking the tip.
4. Add the plugin as a project-scope dependency in each consuming repo's settings, checked into version control.
5. Next time you edit the shared skill, open it as a PR and have a teammate review the diff before bumping any repo's pin.

Where this breaks

Plugin skills don't sync automatically across every surface — a skill uploaded to claude.ai is separate from one in a Claude Code plugin, and each surface needs its own distribution path (Agent Skills overview). Cross-tool portability is improving — the Agent Skills format itself became an open standard in December 2025, adopted by tools including Cursor, GitHub Copilot, VS Code, and Gemini CLI alongside Claude (SiliconANGLE, December 2025; agentskills.io) — but a Claude Code-specific frontmatter field like allowed-tools won't carry over to a tool that only implements the base spec. And pinning versions only helps if someone actually bumps them; a skill repo nobody updates is just a more elaborate way to freeze a stale prompt.

Next: why long agent sessions degrade, and what to do about it.