Door Agent-skills delen tussen repositories zonder drift
Voorkom dat gekopieerde agent-skills onderling gaan afwijken. Behandel skills als dependencies door ze in één centrale repository te beheren en per project vast te pinnen.
Agent-skills delen tussen repositories
Om agent-skills tussen repositories te delen, stopt u met het kopiëren van bestanden en gaat u over op een afhankelijkheidsmodel. Beheer één repository voor skills, voorzie deze van tags en laat elk project een specifieke tag vastzetten (pinnen). Voeg vervolgens per skill een smoke-test toe en beoordeel elke update op dezelfde wijze als u een update van een dependency beoordeelt.
Dit bestaat uit vier onderdelen: een gedeelde bron van waarheid, een vastgezette versie per repository, een smoke-test per skill en een beoordelingsproces. Hieronder wordt uitgelegd waarom elk onderdeel nodig is, wat de tools die in 2026 verschijnen hieraan bijdragen en hoe u dit volledig opbouwt op een zelfgehoste git-remote zonder externe diensten.
Een agent-skill is een map die een SKILL.md-bestand bevat, inclusief alle benodigde scripts en referentiebestanden. Als deze eenheid nieuw voor u is, lees dan eerst wat een agent-skill is en hoe SKILL.md werkt. Deze pagina behandelt de supply chain rondom die eenheid.
Waar een skill zich bevindt en waarom delen lastig is
Claude Code laadt skills vanaf drie locaties en de skills-documentatie benoemt elk pad.
~/.claude/skills/<skill-name>/SKILL.mdis persoonlijk. Deze wordt geladen in al uw projecten en in die van niemand anders..claude/skills/<skill-name>/SKILL.mdis op projectniveau. Deze wordt geladen voor iedereen die die repository uitcheckt.<plugin>/skills/<skill-name>/SKILL.mdwordt meegeleverd in een plugin. Deze wordt geladen waar die plugin ook is ingeschakeld.
De middelste optie is de nuttige voor een team, omdat deze wordt gecommit en iedereen die de repo kloont deze ontvangt. Hier begint echter ook de problematiek. Een skill in .claude/skills/ hoort bij één repository. U heeft acht repositories. Dus de skill wordt acht keer gekopieerd.
De frontmatter biedt geen uitkomst. De Agent Skills-specificatie staat zes keys toe, en de distributiepaden die dit afdwingen tonen de lijst wanneer u een andere gebruikt:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameLet op wat ontbreekt: er is geen version-key. Niets in het bestand legt vast welke kopie nieuwer is. Dat is logisch, omdat een skill een document is in plaats van een pakket. Het betekent wel dat versiebeheer moet komen van de laag rondom het bestand, en die laag is uw verantwoordelijkheid.
Probleem één: acht kopieën die stilletjes uiteenlopen
Kopiëren en plakken werkt op de eerste dag. Het faalt op dag zestig. Iemand corrigeert een onjuiste instructie in de payments-repo en past de andere zeven niet aan. Iemand anders voegt een regel toe over paginering in orders. Nu geeft dezelfde vaardigheidsnaam twee verschillende beoordelingen, afhankelijk van de map waarin de agent is gestart, en geen van de ontwikkelaars is hiervan op de hoogte.
Het falen is geruisloos omdat er geen foutstatus is. Een vaardigheid is proza. Een verouderde instructie produceert een zelfverzekerd, foutief antwoord, wat de kostbare variant is. Niets in de agent vergelijkt uw kopie met die van anderen, dus het enige signaal is dat iemand opmerkt dat twee repo's niet overeenstemmen.
Probleem twee: er wordt geen versie vastgelegd
Zelfs wanneer een team kennis op één plek bijhoudt, is de gebruikelijke methode voor het delen een kopieerstap: een installatiescript, een curl-regel in het onboarding-document, of een shell-alias die een map synchroniseert. Al deze methoden installeren wat er op dat moment aan het begin van de branch staat.
Dit betekent dat twee ontwikkelaars die aan dezelfde commit van dezelfde applicatie werken, verschillende instructies kunnen uitvoeren, omdat zij de synchronisatie op verschillende dagen hebben uitgevoerd. Het betekent ook dat u de vraag die ertoe doet na een foutieve agent-run niet kunt beantwoorden: welke versie van de skill heeft dit geproduceerd? Zonder een vastgelegde revisie is de run niet reproduceerbaar, waardoor het bugrapport niet bruikbaar is.
Probleem drie: niemand weet of de skill nog werkt
Een skill heeft geen compiler. Het zijn instructies gericht aan een model, waardoor deze kan stoppen met werken terwijl het bestand byte voor byte identiek blijft. Een model-upgrade verandert de mate waarin een lange instructie wordt opgevolgd. Een command line tool die door de skill wordt aangeroepen, wijzigt de naam van een flag. Een URL in een referentiebestand geeft een 404-foutmelding en de agent werkt vervolgens op basis van de foutpagina.
In al deze gevallen treedt er geen duidelijke fout op. De agent geeft nog steeds antwoord. Het antwoord is alleen slechter dan de vorige maand, wat lastig te detecteren is bij het beoordelen van individuele pull requests.
Wat de tools die in 2026 verschijnen oplossen
Er zijn momenteel diverse oplossingen in ontwikkeling, maar er is nog geen consensus over waar de versie moet worden opgeslagen.
Lockfiles. De command-line tool skills van Vercel Labs (vercel-labs/skills, MIT-licentie, v1.5.22 per 5 augustus 2026) installeert skills vanuit een git-repository in de map die uw agent verwacht. De tool kent de structuur voor meer dan zeventig agents. npx skills add <repo> installeert, npx skills update voert upgrades uit en npx skills list toont de huidige status. Het overzicht van wat is geïnstalleerd wordt per gebruiker bijgehouden in plaats van per repository. Een openstaande aanvraag in dat project (issue 283) vraagt om een skills install-commando dat alle bijgehouden skills opnieuw installeert vanuit het lockfile, zodat een tweede machine over dezelfde set beschikt. Beschouw die aanvraag als een statusrapport. Het concept van het lockfile is definitief. Het onderdeel voor projectspecifieke configuratie is nog in ontwikkeling.
Specificaties en tests. SkillSpec benadert het vraagstuk vanuit een andere hoek. Het beschouwt een SKILL.md als een contract dat moet worden gecontroleerd in plaats van als tekst die moet worden vertrouwd. Het gestelde doel is om skills "volgbaar, testbaar en bewijsbaar" te maken. skillspec doctor <path> rapporteert waar een agent waarschijnlijk de draad kwijtraakt. skillspec boundary map <path> rapporteert wat de skill kan bereiken en skillspec boundary assess <path> rangschikt deze bevindingen op risico. Het is een Rust-crate, dubbel gelicentieerd onder MIT of Apache 2.0, met versie 0.2.2 per 29 juli 2026. Installeer de vastgezette versie in plaats van de nieuwste:
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked bouwt met de afhankelijkheidsversies waarmee de crate is gepubliceerd, zodat de build niet onbedoeld verandert. skillspec --version hoort 0.2.2 weer te geven. Een ander getal betekent dat een ouder binair bestand eerder in uw PATH voorrang krijgt.
Vendor-praktijken. Google heeft in een artikel over hoe het agent-skills bouwt, test en schaalt beschreven hoe het de skills in google/skills beheert. Als men de schaal weglaat, is het mechanisme gewone continuous integration (CI). Elke skill doorloopt linters voor frontmatter-metadata, regelaantallen, mapstructuur en naamgeving voordat deze wordt samengevoegd. Een link-checker laat de build falen bij elke URL die een 404-foutmelding geeft; dit detecteert aannemelijke links die door een agent zijn verzonnen. Auteurs moeten naast de skill ook een evaluatie-promptsuite en een beoordelingsrubriek aanleveren. Geplande evaluatietaken draaien vervolgens wekelijks over de gehele bibliotheek om regressies op te sporen, en elke skill heeft een aangewezen eigenaar die verantwoordelijk is voor herstel wanneer de kwaliteit afneemt.
Het patroon onder de drie antwoorden
U hoeft niet een van deze opties te kiezen. Daaronder ligt een enkele vorm, en standaard git biedt u alles wat daarvoor nodig is.
- Eén bron van waarheid. De skill heeft precies één thuisbasis en elk repository verwijst naar die basis in plaats van een kopie te bevatten.
- Een vastgezette versie per repository. Elk project legt de exacte revisie vast die het gebruikt, waardoor een upgrade een commit in dat project is met een auteur en een datum.
- Een smoke test per skill. Eén uitvoerbare controle die bewijst dat de skill nog steeds het resultaat levert dat het belooft.
- Een reviewpad. Een wijziging aan een gedeelde skill doorloopt een review, en elke afnemer ziet een diff voordat deze wordt overgenomen.
Dat is de vorm van een afhankelijkheid. Skills werden sneller een gedeeld artefact dan dat de tooling eromheen groeide; daarom is de tooling die u al vertrouwt de veiligste keuze.
Een indeling voor een klein team op een zelfgehoste git-remote
Eén repository bevat de vaardigheden. Er staat niets anders in, waardoor de geschiedenis fungeert als een changelog van instructies.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdReleases zijn tags. Gebruik geannoteerde tags, omdat deze een bericht en een datum bevatten. Schrijf het bericht als de reden waarom een gebruiker de update zou willen installeren:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Als uw remote Gitea, Forgejo, GitLab of een bare repository via SSH op uw eigen VPS is, verandert er niets aan wat hieronder volgt. Alles hier is git plus een symlink.
Pinning met een git submodule
Een submodule legt één specifieke commit van een andere repository vast binnen uw eigen repository. Dat vastgelegde punt is de 'pin'. In elk consumerend project:
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"De symlink is het onderdeel dat dit mogelijk maakt. Een skill-item op projectniveau kan een symlink zijn naar een map elders op de schijf, en Claude Code volgt deze en leest SKILL.md vanuit het doel. De skill wordt dus geladen als een normale project-skill, terwijl de bytes zich bevinden in de submodule op een commit die u heeft gekozen.
Controleer de pin:
git submodule statusEen correcte regel begint met een spatie, gevolgd door de commit, het pad en de dichtstbijzijnde tag:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)Een voorloopteken - betekent dat de submodule nooit is geïnitialiseerd, waardoor .claude/skills/api-review naar niets wijst en de skill zonder foutmelding niet wordt geladen. Los dit op met git submodule update --init. Een voorloopteken + betekent dat de uitgecheckte commit afwijkt van de vastgelegde commit; die ontwikkelaar voert dus instructies uit die niemand anders heeft. Nieuwe clones vereisen git clone --recurse-submodules, en die regel hoort thuis in de README, omdat een standaard clone vendor/agent-skills leeg laat en geen foutmelding geeft.
Upgraden is een bewuste handeling, wat precies het doel is:
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"De regel diff is het revisiepad. Het toont dezelfde wijziging die elke andere consumerende repository zal zien, en het past in een pull request.
Pinnen met een plugin-marketplace als alternatief
Als u liever niet van elke ontwikkelaar vraagt om submodules te leren, dan verzorgt het Claude Code plugin-systeem de distributie voor u, en dit werkt in combinatie met een zelfgehoste remote. Plaats een catalogus op .claude-plugin/marketplace.json in de 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"
}
}
]
}Er zijn hier twee verschillende bronnen in het spel, en het verwarren van deze twee is een veelgemaakte fout. De marketplace-bron, oftewel de locatie waar de catalogus zelf wordt opgehaald, accepteert ref voor een branch of een tag en accepteert geen sha. Een plugin-bron binnen de catalogus accepteert beide, en wanneer beide zijn ingesteld, is de sha de effectieve pin. De exact-commit pin hoort dus in het catalogusitem thuis.
Elke consumerende repository declareert vervolgens de marketplace in zijn gecommitte .claude/settings.json:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Een teamgenoot die de projectmap vertrouwt, krijgt de vraag om de marketplace te installeren, en de plugin wordt voor hen ingeschakeld zonder dat er een wiki-pagina nodig is om hen te vertellen dat ze dit moeten doen. De skills reageren vervolgens op /team-skills:api-review, omdat plugin-skills worden voorzien van een namespace op basis van de plugin-naam en niet kunnen botsen met een project-skill met dezelfde naam. Nadat u een nieuwe tag hebt gepusht, verversen consumers met /plugin marketplace update acme-agents, en voeren daarna /reload-plugins uit als het installatieoverzicht daarom vraagt.
Een smoke test schrijven voor één skill
Een smoke test is een gescript agent-proces dat wordt uitgevoerd tegen een fixture met een bekende fout, aangevuld met één assertie. Claude Code draait non-interactief met -p, en een door de gebruiker aangeroepen skill werkt daar: plaats /skill-name in de prompt-string en deze wordt geëxpandeerd voordat de uitvoering 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 is een kort bestand met één opzettelijke fout. De assertie is dat de skill dit bestand benoemt. jq -e sluit af met een non-zero status wanneer het filter null oplevert; een skill die de ingevoegde fout niet meer detecteert, laat het script dus falen. claude sluit zelf af met een non-zero status wanneer de uitvoering faalt, en set -euo pipefail zet beide vormen van falen om in een mislukte test.
Een model herformuleert antwoorden tussen runs, dus doe nooit een assertie op een volledige zin. Doe een assertie op een identifier die de skill hoort uit te voeren, of op een veld van een schema waar u om heeft gevraagd, en houd de fixture klein zodat de run goedkoop blijft.
Voeg in CI --bare toe. Zonder deze vlag laadt claude -p dezelfde context als een interactieve sessie, inclusief hooks, plugins en CLAUDE.md van de machine waarop het draait; de persoonlijke configuratie van een teamlid kan het resultaat dus beïnvloeden. Bare mode slaat alle automatische detectie over, wat betekent dat ook de skill die u test wordt overgeslagen; laad deze daarom expliciet. Bare mode leest ook uw abonnementsgegevens niet, dus stel eerst ANTHROPIC_API_KEY in de omgeving in:
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 jsonMet --output-format stream-json rapporteert de eerste gebeurtenis van de run welke plugins zijn geladen en bevat deze een plugin_errors-array voor de plugins die niet zijn geladen. Laat de CI-job falen bij een niet-lege plugin_errors. Dit detecteert een pin die verwijst naar een revisie die niet meer bestaat, wat anders zou verschijnen als een agent die uw huisregels stilletjes negeert.
Een gedeelde skill is een uitvoerbare instructie
Twee functies maken dit letterlijk waar, en beide zijn van belang wanneer het bestand van een ander team afkomstig is.
Ten eerste kan een SKILL.md shell-commando's uitvoeren voordat het model iets leest. Een regel zoals deze in de body is preprocessing:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Het commando wordt uitgevoerd op de machine die de skill laadt, en de output vervangt de placeholder in de tekst die het model ontvangt. Een fenced block dat wordt geopend met drie backticks gevolgd door ! voert op dezelfde manier meerdere commando's uit. Niemand keurt dit goed tijdens runtime. Het lezen van een gedeelde skill betekent het lezen van de bijbehorende command substitutions.
Ten tweede kan frontmatter tools vooraf goedkeuren. allowed-tools verleent de vermelde tools zonder een toestemmingsvraag voor de beurt die de skill aanriep. Voor een project-skill wordt die verlening van kracht zodra iemand het dialoogvenster voor workspace-vertrouwen voor de map accepteert. De documentatie van Claude Code stelt de consequentie duidelijk: controleer project-skills voordat u een repository vertrouwt, omdat een skill zichzelf brede tooltoegang kan verlenen.
Behandel een skill-update daarom precies als een dependency-update. Pin op de exacte commit waar het mechanisme dit toestaat, omdat een tag kan worden verplaatst en een branch per definitie beweegt. Op een beveiligde machine vervangt "disableSkillShellExecution": true in de instellingen elke command substitution door de letterlijke tekst [shell command execution disabled by policy] in plaats van deze uit te voeren, en indien toegepast via beheerde instellingen kan een gebruiker dit niet overschrijven. Gebundelde en beheerde skills zijn vrijgesteld van die instelling.
Dezelfde zorg geldt voor wat een skill leest. Een skill die env uitvoert of een configuratiebestand opent, trekt alles wat het vindt in de context van het model; dit is het falen dat wordt behandeld in geheimen buiten de agents houden die u uitvoert. Een skill die een pagina ophaalt of een query uitvoert, is diezelfde blootstelling naar buiten gericht, aangezien opgehaalde tekst in de context belandt en er precies zo uitziet als de instructies die u hebt geschreven. Dit is een grens waarover het de moeite waard is te lezen voordat u een agent naar uw eigen SearXNG-instantie wijst voor webzoekopdrachten.
Wat u moet controleren bij een versie-update
- De diff van elke
SKILL.mdbody, omdat die tekst de instructie bevat die uw agent zal volgen. - Elke command substitution, aangezien deze op uw machine worden uitgevoerd wanneer de skill wordt geladen.
- Elke wijziging aan
allowed-tools, omdat die regel tools toekent zonder dat er een prompt verschijnt. - De testrun achter de tag. Als de gedeelde repository eigen smoke tests in CI uitvoert, moet de tag waaraan u koppelt een geslaagde run hebben.
Een reviewer die de volledige diff niet binnen tien minuten kan lezen, kijkt naar een skill die te groot is geworden. Splits deze op. Hetzelfde argument geldt voor de repository-documenten die uw agents lezen: bewaar duurzame regels in de bestanden beschreven in de AGENTS.md en HUMAN.md splitsing en architecturale overwegingen in een DESIGN.md geschreven voor agents, en laat skills beperkt blijven tot specifieke procedures.
Wanneer een wijziging in een model of tool een skill onklaar maakt
Er veranderen diverse zaken onder de motorkap van een skill zonder dat iemand deze bewerkt. Een model-upgrade verandert de betrouwbaarheid waarmee een lange instructie wordt opgevolgd; een skill die afhankelijk was van het bereiken van stap negen door het model, kan daar plotseling stoppen. Een command line tool hernoemt een flag, waardoor de agent de oude flag uitvoert, de foutmelding leest en gaat improviseren. Een gerefereerde URL geeft een 404-foutmelding. Een agent harness wijzigt de manier waarop skills worden geselecteerd, waardoor een description die voorheen de match won, dat niet langer doet. Wanneer een procedure op die manier voortijdig eindigt, lost een versie-update niets op. De instructies zelf hebben dan een structuur nodig die de laatste stappen afdwingt; dit is de aanpak achter de unlazy skill en de bijbehorende Depth Tree-methode.
Dit is de reden waarom de smoke test zo zwaar weegt in deze opzet. Voer de test van elke skill uit volgens een schema en bij elke push. Google voert om deze reden wekelijks evaluatietaken uit op de gehele bibliotheek, en een wekelijkse cron job op een kleine VPS volstaat voor een team met tien skills. Het is de enige manier om op de hoogte te zijn van defecten voordat een ontwikkelaar dat is.
Portabiliteit helpt ook. De Agent Skills-specificatie beperkt de frontmatter tot zes keys. Een skill die volgens die specificatie is geschreven, werkt daardoor in meer tools dan alleen degene waarvoor u hem heeft geschreven, terwijl elke harness-specifieke key die u toevoegt een gok is op één leverancier. Het schrijven van skills die een modelwissel overleven is een vak apart, dat wordt behandeld in een skill laten werken op elk model.
FAQ
Hoe deel ik één agent-skill over meerdere repositories?
Plaats de skill in een eigen git-repository, tag releases en laat elk consumerend project naar een tag verwijzen in plaats van het bestand te kopiëren. Twee mechanismen werken hiervoor. Een git submodule legt een exacte commit vast, en een symlink vanuit .claude/skills/<name> naar de submodule zorgt ervoor dat deze als een normale project-skill wordt geladen. Een plugin-marketplace doet hetzelfde via /plugin, waarbij de pin wordt gedeclareerd in het .claude/settings.json-bestand van het consumerende project. Beide methoden leggen de versie vast in de git-historie, zodat u kunt achterhalen welke instructies tot een specifieke agent-run hebben geleid.
Kan ik een agent-skill vastzetten op een specifieke versie?
Niet vanuit SKILL.md, omdat die frontmatter geen version-sleutel bevat. De pin moet afkomstig zijn van de laag rondom het bestand. Een git submodule zet standaard een exacte commit vast. In een Claude Code-plugin-marketplace accepteert een plugin-bron ref voor een branch of tag en sha voor een exacte commit, waarbij sha voorrang krijgt als beide aanwezig zijn. De marketplace-bron zelf accepteert alleen ref. Geef de voorkeur aan een commit-pin, omdat een tag kan worden verplaatst nadat u deze heeft gecontroleerd.
Wat moet een smoke-test voor een skill verifiëren?
Verifieer op iets stabiels. Voer de skill non-interactief uit tegen een fixture die een bekende fout bevat en controleer vervolgens of een specifieke identificatie in de output verschijnt, bijvoorbeeld een regel-ID die de skill hoort te rapporteren. Het aanvragen van gestructureerde output met --output-format json en --json-schema maakt de controle exact, en jq -e laat het script falen wanneer de waarde ontbreekt. Verifieer nooit op een volledige zin, omdat een model zijn antwoorden tussen runs door kan herformuleren.
Is het veilig om een gedeelde skill uit de repository van een ander team te installeren?
Behandel het als een code-dependency, omdat het uitvoerbare instructies zijn. Een SKILL.md kan shell-commando's uitvoeren tijdens het laden via de !-commandosubstitutievorm, en het allowed-tools-veld in de frontmatter kan tools vooraf goedkeuren zonder prompt. Bekijk de diff bij elke update, pin naar een exacte commit in plaats van een branch en geef de voorkeur aan een bron die uw eigen team beheert. Op beheerde machines stopt "disableSkillShellExecution": true in de instellingen de uitvoering van commandosubstituties volledig.
Werkt een gedeelde skill in andere agents dan Claude Code?
Dat hangt af van de frontmatter die u gebruikt. De Agent Skills-specificatie definieert zes sleutels: name, description, license, compatibility, metadata en allowed-tools. Een skill die zich tot deze sleutels beperkt, laadt in tools die de specificatie implementeren en werkt ook zonder wijzigingen in Claude Code. Harness-specifieke sleutels en body-functies die buiten de specificatie vallen, worden elders genegeerd of geweigerd; houd deze daarom buiten elke skill die u breed wilt delen.