Agent-skills delen tussen repositories zonder drift

Hoe agent-skills gedeeld kunnen worden tussen repositories

Om agent-skills tussen repositories te delen, stopt u met het kopiëren van bestanden en begint u met het gebruik van afhankelijkheden. Beheer één repository voor skills, voorzie deze van tags en laat elk project een specifieke tag vastleggen (pinnen). Voeg vervolgens per skill een smoke test toe en beoordeel elke update op dezelfde wijze als u een update van een afhankelijkheid beoordeelt.

Dit bestaat uit vier onderdelen: een gedeelde bron van waarheid, een vastgelegde versie per repository, een smoke test per skill en een beoordelingsproces. Alles hieronder legt uit waarom elk onderdeel bestaat, wat de tools die in 2026 worden uitgebracht hieraan bijdragen en hoe u dit geheel opbouwt op een zelfgehoste git-remote zonder tussenkomst van externe diensten.

Een agent-skill is een map die een SKILL.md-bestand bevat, inclusief alle scripts en referentiebestanden die nodig zijn. 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.md is persoonlijk. Deze wordt geladen in al uw projecten en in die van niemand anders.
• .claude/skills/<skill-name>/SKILL.md is op projectniveau. Deze wordt geladen voor iedereen die die repository uitcheckt.
• <plugin>/skills/<skill-name>/SKILL.md wordt 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 het probleem. Een skill in .claude/skills/ hoort bij één repository. U heeft acht repositories. Dus de skill wordt acht keer gekopieerd.

De frontmatter biedt geen hulp. 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, name

Let 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 foutieve 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 stil omdat er geen foutstatus is. Een vaardigheid is proza. Een verouderde instructie produceert een zelfverzekerd, foutief antwoord; dat is de kostbare variant. Niets in de agent vergelijkt uw kopie met die van anderen, dus het enige signaal is een persoon die opmerkt dat twee repo's niet overeenstemmen.

Probleem twee: geen versie-vastlegging

Zelfs wanneer een team vaardigheden op één locatie beheert, is de gebruikelijke deelmethode een kopieerstap: een installatiescript, een curl-regel in het onboarding-document, of een shell-alias die een map synchroniseert. Al deze methoden installeren de versie die op dat moment aan het hoofd 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 er na een foutieve agent-run toe doet niet kunt beantwoorden: welke versie van de vaardigheid heeft dit geproduceerd? Zonder een vastgelegde revisie is de uitvoering 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 vorige maand, wat lastig op te merken is bij het beoordelen van individuele pull requests.

Wat de tools die in 2026 verschijnen oplossen

Er zijn momenteel diverse oplossingen in ontwikkeling, waarbij er geen consensus is 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 ondersteunt de structuur van 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 openstaand verzoek in dat project (issue 283) vraagt om een skills install-commando dat alle gevolgde skills opnieuw installeert vanuit het lockfile, zodat een tweede machine over dezelfde set beschikt. Beschouw dat verzoek als een statusrapport. Het concept van het lockfile is vastgesteld. Het gedeelte voor projectspecifieke configuratie is nog in ontwikkeling.

Specs en tests. SkillSpec benadert het vraagstuk vanuit een andere hoek. Het behandelt een SKILL.md als een contract dat gecontroleerd moet worden in plaats van als tekst die vertrouwd moet worden, met als doel 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, 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 te tonen. Een ander getal betekent dat een ouder binary eerder in uw PATH voorrang krijgt.

Vendor-praktijken. Google heeft beschreven hoe zij de skills in google/skills bouwen in een artikel over hoe zij agent-skills bouwen, testen en schalen. Als men de schaal weglaat, is het mechanisme reguliere 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 worden vervolgens wekelijks uitgevoerd op de gehele bibliotheek om regressies te detecteren, en elke skill heeft een aangewezen eigenaar die verantwoordelijk is voor herstel wanneer de kwaliteit afneemt.

Het patroon onder alle drie de antwoorden

U hoeft niet een van deze opties te kiezen. Daaronder ligt één structuur, en standaard git biedt u alles wat daarvoor nodig is.

1. Eén bron van waarheid. De skill heeft precies één thuisbasis en elk repository verwijst naar die locatie in plaats van een kopie te bevatten.
2. Een vastgezette versie per repository. Elk project legt de exacte revisie vast die het gebruikt, waardoor een upgrade een commit in dat project is, inclusief auteur en datum.
3. Een smoke test per skill. Eén uitvoerbare controle die bewijst dat de skill nog steeds het resultaat levert dat wordt beloofd.
4. Een reviewpad. Een wijziging aan een gedeelde skill doorloopt een review, en elke afnemer ziet een diff voordat deze wordt geaccepteerd.

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 bevindt zich 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.md

Releases 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.0

Als uw remote Gitea, Forgejo, GitLab of een bare repository via SSH op uw eigen VPS is, verandert er niets aan het onderstaande. 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; Claude Code volgt deze en leest SKILL.md vanuit de doelmap. De skill wordt hierdoor geladen als een normale project-skill, terwijl de bestanden zich in de submodule bevinden op een door u gekozen commit.

Controleer de pin:

git submodule status

Een 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 verwijst en de skill zonder foutmelding niet wordt geladen. Herstel dit met git submodule update --init. Een voorloopteken + betekent dat de uitgecheckte commit afwijkt van de vastgelegde commit; de ontwikkelaar voert in dat geval 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 de map vendor/agent-skills leeg laat zonder een foutmelding te geven.

Upgraden is een bewuste handeling, en dat is precies het doel:

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.

Pinning 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 vandaan wordt gehaald, accepteert ref voor een branch of een tag en accepteert geen sha. Een plugin-bron binnen de catalogus accepteert beide; wanneer beide zijn ingesteld, is de sha de effectieve pin. De pin voor de exacte commit 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 melding om de marketplace te installeren, en de plugin wordt voor hen ingeschakeld zonder dat er een wiki-pagina nodig is om uit te leggen hoe dit moet. 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 conflicteren met een project-skill met dezelfde naam. Nadat u een nieuwe tag hebt gepusht, verversen consumers met /plugin marketplace update acme-agents en voeren ze daarna /reload-plugins uit als het installatieoverzicht daarom vraagt.

Een smoke test schrijven voor één skill

Een smoke test is een gescripte agent-run tegen een fixture met een bekende fout, plus éé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 uitgebreid voordat de 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/null

fixtures/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, dus een skill die de geplaatste fout niet meer opmerkt, laat het script falen. claude sluit zelf af met een non-zero status wanneer de run faalt, en set -euo pipefail verandert beide vormen van falen in een mislukte test.

Een model herformuleert zijn 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 vroeg, 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, waardoor de persoonlijke configuratie van een teamgenoot het resultaat kan 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 abonnementslogin 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 json

Met --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 vangt een pin op die gericht is op een revisie die niet langer 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 uitvoer vervangt de placeholder in de tekst die het model ontvangt. Een fenced block dat wordt geopend met drie backticks gevolgd door ! voert op dezelfde wijze 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 heeft aangeroepen. Voor een project-skill treedt die toekenning in werking 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 toegang tot tools 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 verplaatst kan worden 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; indien toegepast via beheerde instellingen kan een gebruiker dit niet overschrijven. Gebundelde en beheerde skills zijn vrijgesteld van die instelling.

Dezelfde zorgvuldigheid geldt voor wat een skill leest. Een skill die env uitvoert of een configuratiebestand opent, haalt 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 terechtkomt 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.

Waar u op moet letten bij een versie-update

• De diff van elke SKILL.md body, 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 toestaat zonder dat er om bevestiging wordt gevraagd.
• De testrun achter de tag. Als de gedeelde repository eigen smoke tests uitvoert in CI, moet de tag waaraan u koppelt een geslaagde run hebben.

Een reviewer die niet binnen tien minuten de volledige diff kan lezen, kijkt naar een skill die te groot is geworden. Splits deze op. Hetzelfde argument geldt voor de documenten in de repository die uw agents lezen: bewaar duurzame regels in de bestanden die worden beschreven in de splitsing tussen AGENTS.md en HUMAN.md 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 mee stoppen. Een command line tool hernoemt een flag, waardoor de agent de oude flag uitvoert, de foutmelding leest en improviseert. Een gerefereerde URL geeft plotseling een 404-foutmelding. Een agent-harness wijzigt de manier waarop skills worden geselecteerd, waardoor een description die voorheen de match won, dat nu niet meer doet.

Dit is de reden waarom de smoke test in deze opzet zo zwaar weegt. Voer de test van elke skill zowel volgens een schema als bij een push uit. 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 van een defect te vernemen voordat een ontwikkelaar dat doet.

Portabiliteit helpt ook. De Agent Skills spec beperkt frontmatter tot zes keys, waardoor een skill die volgens die specificatie is geschreven, in meer tools laadt dan alleen degene waarvoor u hem schreef, terwijl elke harness-specifieke key die u toevoegt een weddenschap op één leverancier is. Het schrijven van skills die een modelwissel overleven is een discipline op zich, die 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 de consumerende repository. 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 worden ingesteld in de laag rondom het bestand. Een git submodule zet van nature 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; de sha krijgt voorrang 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 basis van stabiele elementen. Voer de skill non-interactief uit tegen een fixture die een bekende fout bevat en controleer of een specifiek identificatiemiddel in de output verschijnt, zoals 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 basis van 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 !-commando-substitutievorm, en het allowed-tools-veld in de frontmatter kan tools vooraf goedkeuren zonder dat er om bevestiging wordt gevraagd. Bekijk de diff bij elke update, pin op een exacte commit in plaats van op 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 commando-substituties 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 laadt tevens zonder wijzigingen in Claude Code. Specifieke sleutels voor een bepaalde omgeving en body-functies die buiten de specificatie vallen, worden elders genegeerd of geweigerd; houd deze daarom buiten elke skill die u breed wilt delen.