Share Agent Skills Across Repos Without Drift
Stop copying skills into eight repos and watching versions drift. Keep one shared repo, tag releases, pin one version per project, and review every bump.
Agent skills repo-bendin share ken
If you wan share agent skills across repos, stop copying the file and start depending on am. Keep one skills repository, tag am, then make each project pin one tag. Add one smoke test for each skill, and review every bump the same way you review dependency bump.
Na four parts dey: one shared source of truth, one pinned version for each repository, one smoke test for each skill, and one review path. Everything wey follow explain why each part dey exist, wetin the tools wey release for 2026 do about am, and how to build the whole setup for self-hosted git remote without using outside git host or package registry. The smoke tests na the only exception. Dem dey run Claude Code, wey dey send every request go model API, so that step still comot from your server.
Agent skill na folder wey hold one SKILL.md file, plus any scripts and reference files wey e need. If that unit still new to you, first read wetin agent skill be and how SKILL.md dey work. This page na about the supply chain around that unit.
Where skill dey, and why sharing am hard
Claude Code dey load skills from the locations below and other ones, and skills documentation list each path.
.claude/skills/<skill-name>/SKILL.mdinside the managed settings directory na the enterprise location. E dey load for every user for machines wey organization deploy am.~/.claude/skills/<skill-name>/SKILL.mdna personal. E dey load for all your projects, but e no dey load for anybody else..claude/skills/<skill-name>/SKILL.mdna project level. E dey load for anybody wey check out that repository.<plugin>/skills/<skill-name>/SKILL.mddey ship inside plugin. E dey load anywhere wey that plugin dey enabled.
Claude Code still dey load skills from nested project directories, directories wey you supply with --add-dir, and skills wey you enable for your claude.ai account.
The project level one na the useful one for team, because e dey committed and everybody wey clone the repo go get am. Na there the wahala start too. Skill for .claude/skills/ belong to one repository. You get eight repositories. So the skill go copy eight times.
The frontmatter no fit help here. Agent Skills spec allow six keys, and the distribution paths wey enforce am go print the list when you use another one:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameNotice wetin no dey there: no version key dey. You fit record version under metadata, but the spec no define dependency pin or update mechanism. This one make sense, because skill na document, no be package. But e mean say versioning must come from the layer around the file, and na you go handle that layer.
Problem wan: eight copies wey quietly dey diverge
Copy-paste fit work for day one. E go fail for day sixty. Person fit fix wrong instruction for payments repo but no touch the other seven. Another person fit add rule about pagination for orders. Now the same skill name dey give two different reviews, depending on which directory agent start from, and neither developer know.
The failure dey happen quietly because no error state dey. Skill na prose. Stale instruction fit produce confident but wrong answer, and na this kind error dey cost plenty. Nothing for agent dey compare your copy with another person's own, so the only signal na when person notice say two repos no agree.
Problem two: nothing pin a version
Even when team keep skills for one place, the normal sharing method na copy step: setup script, one curl line for onboarding doc, or shell alias wey dey sync one folder. All of dem install anything wey dey for head of the branch at that time.
This mean say two developers wey dey use the same commit of the same application fit dey run different instructions, because dem run the sync on different days. E also mean say after bad agent run, you no fit answer the important question: which version of the skill produce this? If you no record the revision, you no fit reproduce the run, so the bug report no get enough information to act on.
Problem three: nobody know whether the skill still dey work
Skill no get compiler. Na instruction wey dem aim at model, so e fit stop to work even when the file remain exactly the same byte for byte. Model upgrade fit change how well e dey follow long instruction. Command line tool wey the skill dey call fit rename flag. URL for reference file fit start return 404, and agent go use the error page do work.
For all these cases, nothing go fail loudly. Agent still dey answer. Na only say the answer don worse pass how e be last month. One pull request at a time, this kind change hard to notice.
Wetin the tools wey dey release for 2026 dey solve
Several answers dey land now, and dem no agree on where the version suppose dey.
Lockfiles. The skills command line tool from Vercel Labs (vercel-labs/skills, MIT licensed, v1.7.2 as of 9 October 2026) dey install skills from git repository go any directory wey your agent expect, and e sabi the layout for more than seventy agents. npx skills add <repo> dey install, npx skills update dey upgrade, and npx skills list dey show wetin you get. E dey keep two lock files. Global one for ~/.agents/.skill-lock.json dey record wetin one user don install. Since v1.4.1 (20 February 2026), installation for project scope dey also write skills-lock.json for project root, and the tool source code talk say you suppose commit that file to version control. npx skills experimental_install dey restore project skills from am. Issue 283, wey request skills install command to restore global lock file for another machine, dem close am as not planned on 5 November 2026; the maintainer identify am as the same request as issue 549. Read both as status report. Per-project lockfile dey. For released v1.8.1, help still label the restore command experimental, but npx skills install without source dey also restore the project lockfile.
Specs and tests. SkillSpec dey take the other approach. E dey treat SKILL.md as contract wey you need check, instead of prose wey you just trust, with the stated goal to make skills "followable, testable, and provable". skillspec doctor <path> dey report where agent likely go lose the thread. skillspec boundary map <path> dey show wetin the skill contain, and skillspec boundary assess <path> dey report wetin e fit reach, ranked by risk. Na Rust crate, and MIT or Apache 2.0 license cover am. Version 0.2.2 dem publish on 29 July 2026, and na still the newest for crates.io as of 10 October 2026. Install the pinned version instead of the newest one:
cargo install skillspec --version 0.2.2 --locked
skillspec --versionSince Cargo 1.100, wey dem release on 12 November 2026, cargo install dey use the packaged lockfile by default, and --locked no dey do anything. skillspec --version suppose print 0.2.2. If different number show, older binary earlier inside your PATH dey win.
Vendor practice. Google explain how e dey build the skills for google/skills inside post about how e dey build, test and scale agent skills. If you remove the scale, the mechanism na ordinary continuous integration (CI). Every skill dey pass linters for frontmatter metadata, line count, directory layout and naming before dem merge am. Link checker dey fail the build for any URL wey return 404, and this dey catch plausible link wey agent invent. Authors must provide evaluation prompt suite and scoring rubric together with the skill. Scheduled evaluation jobs dey run every week against the whole library to catch regressions, and every skill get named owner wey suppose fix am when quality drop.
The pattern wey dey under all three answers
You no need choose any of dem. Under all of dem, one single structure dey, and plain git give you everything inside am.
- One source of truth. The skill get exactly one home, and every repository refer to that home instead of keeping copy.
- One pinned version for each repository. Every project record the exact revision wey e dey use, so upgrade na commit for that project with author and date.
- One smoke test for each skill. One runnable check wey prove say the skill still dey produce the result wey e promise.
- One review path. Change to shared skill must pass through review, and every consumer go see diff before e accept am.
Na this be the structure of dependency. Skills become shared artifacts faster than tooling grow around dem, so the tooling wey you already trust na the safest thing to use.
A layout for small team wey dey use self-hosted git remote
One repository go hold the skills. Nothing else go dey inside am, so the history go read like changelog for instructions.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdReleases na tags. Use annotated tags, because dem carry message and date. Write the message as the reason why consumer go want the bump:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0If your remote na Gitea, Forgejo, GitLab or bare repository over SSH for your own VPS, nothing for wetin follow go change. Everything here na git plus symlink.
Git submodule dey pin
A submodule dey record one exact commit from another repository inside your repository. Na this record be the pin. For each project wey dey use am:
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"The symlink na the part wey make this work. Skill entry for project level fit be symlink to directory for another place for disk, and Claude Code go follow am and read SKILL.md from the target. So the skill go load like normal project skill, while the bytes dey inside the submodule for commit wey you choose.
Check the pin:
git submodule statusHealthy line dey start with one space, then the commit, then the path, then the nearest tag:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)If line start with -, e mean say dem never initialise the submodule, so .claude/skills/api-review dey point to nothing and the skill no go load quietly. Use git submodule update --init to fix am. If line start with +, e mean say the checked-out commit different from the one wey dem record, so that developer dey run instructions wey nobody else get. New clones need git clone --recurse-submodules, and that line suppose dey inside the README, because plain clone go leave vendor/agent-skills empty and e no go print error.
Upgrade na deliberate process, and na the main reason for the pin:
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"The diff line na the review path. E show the same change wey every other consuming repo go see, and e fit enter pull request.
Pinning with a plugin marketplace instead
If you no wan ask every developer to learn submodules, Claude Code plugin system go handle the distribution for you, and e work with a self-hosted remote. Put catalog for .claude-plugin/marketplace.json inside the skills repository:
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}Two different sources dey involved here, and na common mistake to mix dem up. Marketplace source, meaning where dem dey fetch the catalog itself from, accepts ref for branch or tag and, for Claude Code v2.1.324 or later, full lowercase commit SHA; e no accept separate sha field. Plugin source inside the catalog accepts both, and when both dey set, sha na the effective pin. Pin the catalog through ref for its marketplace source, and pin the plugin through sha for the catalog entry. The type names dey different too. Inside the catalog, url mean git repository wey Claude Code go clone. For marketplace source, url mean direct link to marketplace.json file, while git repository na git.
Each repository wey dey consume am then declare the marketplace inside its committed .claude/settings.json:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code go register the marketplace for teammate after dem accept workspace trust dialog for the project folder, without wiki page wey tell dem to do am. The catalog entry point to git URL instead of relative path, so the plugin itself no go install from the repository settings alone. Each teammate run claude plugin install team-skills@acme-agents --scope project once, and until dem do am, Claude Code go report say the plugin dey enabled for project settings but e never install. The skills then answer to /team-skills:api-review, because plugin skills dey use plugin name as namespace and dem no fit clash with project skill wey get the same name. After you push new tag and update the pins for the catalog and consuming repositories, consumers refresh with /plugin marketplace update acme-agents, then run /reload-plugins if the install summary ask for am.
Smoke test wey you write for one skill
Smoke test na scripted agent run against fixture wey get known fault, plus one assertion. Claude Code dey run non-interactively with -p, and skill wey user invoke dey work there: put /skill-name inside prompt string and e go expand before run start.
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md na short file wey get one deliberate fault. The assertion na say skill go name am. jq -e exits non-zero when its filter produces null, so skill wey stop catching the seeded fault go fail the script. claude itself exits non-zero when the run fail, and set -euo pipefail turns either failure into failed test.
Model fit reword its answers between runs, so never assert against whole sentence. Assert against identifier wey skill suppose emit, or field for schema wey you request, and keep fixture small so run no cost much.
For CI, add --bare. Without am, claude -p loads the same context wey interactive session for load, including hooks, plugins and CLAUDE.md from the machine wey e dey run on. This means teammate personal configuration fit change the result. Bare mode skips auto-discovery, except skills for .claude/skills/ under directory wey you explicitly supply with --add-dir. E skips the project skill wey you dey test here, so load that one explicitly. Bare mode no read your subscription login too, so set ANTHROPIC_API_KEY for environment first:
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format jsonPlugin wey you load with --plugin-dir takes its name from .claude-plugin/plugin.json. Without that manifest, dem go name am after its directory. Commit a plugin.json with "name": "team-skills" beside the catalog for skills repository, or command above go need call /agent-skills:api-review instead.
With --output-format stream-json, system/init event reports which plugins load and carries plugin_errors array for the ones wey no load. E opens the stream unless startup events come first. Make CI job fail when plugin_errors no empty. This catches pin wey point to revision wey no longer exist. Otherwise, agent fit just ignore your house rules quietly.
Shared skill na executable instruction
Two features make that meaning literal, and both matter when file come from another team.
First, a SKILL.md fit run shell commands before model read anything. A line like this inside the body na preprocessing:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Command go run for the machine wey dey load the skill, and e output go replace the placeholder for the text wey model receive. A fenced block wey start with three backticks followed by ! go run several commands the same way. Nobody go get prompt for any of this when e dey run. Claude Code go check every command against your permission rules. Outside auto mode, command wey those rules no allow go abort the skill, unless the skill pre-approve am through the second feature below. Deny and ask rules still override that pre-approval. To read shared skill mean say you dey read its command substitutions.
Second, frontmatter fit pre-approve tools. allowed-tools grants the listed tools without permission prompt for the turn wey invoke the skill. Workspace trust no dey control that grant: Claude Code go apply project skill's allowed-tools even for a -p run inside folder wey nobody trust. Claude Code documentation state the consequence plainly: skill fit grant itself broad tool access, so review the allowed-tools of skills wey dey checked into repository before you run Claude Code there. Organization fit withhold the field from project and personal skills by setting allowManagedPermissionRulesOnly for managed settings, but this need Claude Code v2.1.282 or later.
So treat skill bump exactly like dependency bump. Pin am by exact commit wherever the mechanism allow, because tag fit move and branch dey move by definition. For locked-down machine, "disableSkillShellExecution": true for settings go replace every command substitution with literal text [shell command execution disabled by policy] instead of running am, and when managed settings apply am, user no fit override am. Bundled and managed skills no dey affected by that setting.
The same care apply to wetin skill dey read. Skill wey run env or open config file go pull anything wey e find into model context. Na this failure how to keep secrets out of the agents you run cover. Skill wey fetch page or run query expose that same risk outward, because retrieved text enter context and look exactly like instructions wey you write. This boundary worth reading about before you point an agent at your own SearXNG instance for web search.
Wetín to read when version change
- The diff of every
SKILL.mdbody, because na that text your agent go follow. - Every command substitution, because dem dey run for your machine when the skill load.
- Any change to
allowed-tools, because that line dey grant tools without prompt. - The test run behind the tag. If the shared repository dey run im own smoke tests for CI, the tag wey you dey pin to suppose get green run attached.
Reviewer wey no fit read the whole diff within ten minutes dey look at skill wey don too big. Split am. The same thing apply to repository documents wey your agents dey read: keep durable rules for the files wey the AGENTS.md and HUMAN.md split describe, keep architectural reasoning for a DESIGN.md wey agents fit read, and make skills remain narrow procedures.
Wen model or tool change dey break skill
Plenty things fit change underneath skill without anybody edit am. Model upgrade fit change how well e dey follow long instruction, so skill wey depend on model to reach step nine fit stop before e reach there. Command line tool fit rename flag, so agent go run the old flag, read the error, then improvise. Referenced URL fit start return 404. Agent harness fit change how e dey select skills, so a description wey used to win the match fit stop winning. Wen procedure start dey end early like this, no version bump go fix am. The instructions themselves need structure wey go force the final steps. Na this approach dey behind the unlazy skill and e Depth Tree method.
Na why smoke test dey carry the main weight for this setup. Run each skill test on schedule and also on every push. Google dey run evaluation jobs every week against the whole library for this reason. For team wey get ten skills, one weekly cron job for small VPS dey enough. Na only this way you fit hear about the breakage before developer notice am.
Portability still dey help. Agent Skills spec keep frontmatter to six keys, so skill wey follow that spec fit load for tools beyond the one wey you write am for. But every harness-specific key wey you add na bet on one vendor. Writing skills wey go survive model swap na separate discipline. making skill work on any model cover am.
FAQ
How I fit share one agent skill across plenty repositories?
Put the skill for one dedicated git repository, tag releases for there, and make each project wey dey use am reference one tag instead of copying the file. Two methods dey work. A git submodule records exact commit, and symlink from .claude/skills/<name> enter the submodule make e load like normal project skill. A plugin marketplace do the same work through /plugin, with the pin declared for the consuming repository .claude/settings.json. Both methods put the version for git history, so you fit answer which instructions produce one particular agent run.
I fit pin agent skill to one specific version?
No be from inside SKILL.md, because that frontmatter no get version key. The layer around the file suppose provide the pin. A git submodule pins exact commit by design. For Claude Code plugin marketplace, plugin source accepts ref for branch or tag, and sha for exact commit; when both dey present, sha na the one wey take effect. The marketplace source itself accepts ref for branch, tag or, for Claude Code v2.1.324 or later, full lowercase commit SHA. Prefer commit pin, because person fit move tag after you don review am.
Wetin skill smoke test suppose assert?
Assert on something wey stable. Run the skill non-interactively against fixture wey contain known fault, then check say specific identifier dey inside the output, like rule id wey the skill suppose report. Requesting structured output with --output-format json and --json-schema make the check exact, and jq -e make the script fail when the value no dey. No ever assert on full sentence, because model fit reword the answers between runs.
E safe to install shared skill from another team repository?
Treat am like code dependency, because na executable instruction. A SKILL.md fit run shell commands when e load through ! command substitution form, and frontmatter allowed-tools field fit pre-approve tools without prompt. Read the diff every time you bump version, pin to exact commit instead of branch, and prefer source wey your own team dey control. For managed machines, "disableSkillShellExecution": true for settings stop command substitutions inside user, project, plugin and additional-directory skills from running; bundled and managed skills no dey affected.
Shared skill go work for agents wey no be Claude Code?
E depend on the frontmatter wey you use. Agent Skills spec define six keys: name, description, license, compatibility, metadata and allowed-tools. Skill wey use only those keys go load across tools wey implement the spec, and e go also load for Claude Code without changes. Harness-specific keys and body features wey no dey inside the spec go either ignore or reject elsewhere, so no put dem inside skill wey you plan share widely.