How I Solved Agent Skill Drift Across Repos with Capshelf

The core problem is simple: when you work across several codebases at once, the Claude Code skills you curate in one repo inevitably diverge from every other copy. I had a security-review skill that kept getting refined in project A, but project B was still running an older version — and I had no reliable way to know which was which. Symlinking into a shared directory solved the duplication but introduced a worse bug: editing the skill for one repo silently changed behavior in every other repo that used it.

That friction pushed me to build Capshelf, a CLI designed to keep your skills, settings, and MCP server entries in a single shared git repo while letting each project pin its own exact copy. It currently covers Claude Code, Codex, and Pi, and supports pinning skills, Pi extensions, individual settings values, and MCP server declarations.

The core mechanism is a manifest-plus-lockfile model. The manifest lists what's installed; the lockfile records content hashes and source commits for every item. Think of it like vendoring dependencies — except for agent configurations.

Setting up a shared skills repo is straightforward:

1. Initialize Capshelf in one of your existing repositories, pointing it at a new empty git repo:

capshelf init --data /some/local/gitrepo --no-upstream

2. Share a local skill into that data repo with a specific visibility scope:

capshelf share security-review --to project

Use --to local if you want to promote a skill without pinning it for all project members:

capshelf share design-review --to local

This starts tracking the skill under Capshelf and records the current version in the consuming repository's lockfile.

3. In a different project, pull in the skill:

capshelf add design-review

If you or your agent modifies the design-review skill, you can promote the change so other projects can pick it up. Every project stays pinned to an exact content hash, so a promotion in project A does not touch project B until someone explicitly runs capshelf update there.

The workflow maps closely to how Terraform handles plan and apply — you promote changes, review them, and let downstream consumers decide when to pull them in.

In a team setting, sharing a skill means promoting it, then pushing or opening a PR. You review the diff like any other code change. When a teammate clones the repo, they get the exact versions the lockfile pins, and a CI check can flag any PR whose configuration drifted from the locked state.

To install, you can grab it through Homebrew:

brew install genged/tap/capshelf

The repository lives at github.com/genged/capshelf if you want to inspect the source or contribute. I've been using this in production across four repos for about two months now, and the reduction in configuration drift has been noticeable — especially on teams where multiple people are iterating on agent prompts simultaneously. It's a small tool, but it solves a real coordination problem that most teams don't even realize they have until a skill update silently breaks a review workflow in one of their projects.