Agent-Skills über Repositories hinweg ohne Drift teilen

So teilen Sie Agent-Skills über mehrere Repositories hinweg

Um Agent-Skills über mehrere Repositories hinweg zu teilen, kopieren Sie die Datei nicht mehr, sondern machen Sie sie zu einer Abhängigkeit. Verwenden Sie ein zentrales Skills-Repository, versehen Sie es mit einem Tag, und lassen Sie jedes Projekt einen Tag festlegen. Fügen Sie anschließend für jeden Skill einen Smoke-Test hinzu, und prüfen Sie jede Aktualisierung genauso wie die Aktualisierung einer Abhängigkeit.

Das umfasst vier Teile: eine gemeinsame Quelle der Wahrheit, eine festgelegte Version pro Repository, einen Smoke-Test pro Skill und einen Prüfprozess. Im Folgenden wird erklärt, warum jeder Teil erforderlich ist, wie die im Jahr 2026 veröffentlichten Tools damit umgehen und wie Sie das Gesamtsystem auf einem selbst gehosteten Git-Remote aufbauen, ohne einen externen Git-Host oder eine Paketregistrierung zu verwenden. Die Smoke-Tests sind die einzige Ausnahme. Sie führen Claude Code aus, das jede Anfrage an eine Model-API sendet. Dieser Schritt verlässt daher weiterhin Ihren Server.

Ein Agent-Skill ist ein Verzeichnis mit einer SKILL.md-Datei sowie allen benötigten Skripten und Referenzdateien. Wenn diese Einheit für Sie neu ist, lesen Sie zuerst was ein Agent-Skill ist und wie SKILL.md funktioniert. Auf dieser Seite geht es um die Lieferkette rund um diese Einheit.

Wo eine Skill liegt und warum das Teilen schwierig ist

Claude Code lädt Skills unter anderem aus den folgenden Verzeichnissen. Die Dokumentation zu Skills nennt jeden dieser Pfade.

• .claude/skills/<skill-name>/SKILL.md im Verzeichnis für verwaltete Einstellungen ist der Speicherort für Unternehmen. Der Skill wird für jeden Benutzer auf Systemen geladen, auf denen eine Organisation ihn bereitstellt.
• ~/.claude/skills/<skill-name>/SKILL.md ist benutzerspezifisch. Der Skill wird in allen Ihren Projekten geladen, aber in keinem Projekt anderer Benutzer.
• .claude/skills/<skill-name>/SKILL.md gilt auf Projektebene. Der Skill wird für alle Benutzer geladen, die dieses Repository auschecken.
• <plugin>/skills/<skill-name>/SKILL.md ist Bestandteil eines Plugins. Der Skill wird überall geladen, wo dieses Plugin aktiviert ist.

Claude Code lädt Skills außerdem aus verschachtelten Projektverzeichnissen, aus Verzeichnissen, die mit --add-dir angegeben werden, sowie aus Skills, die für Ihr claude.ai-Konto aktiviert sind.

Der Speicherort auf Projektebene ist für ein Team am nützlichsten, weil der Skill versioniert wird und jeder, der das Repository klont, ihn erhält. Genau dort beginnen aber die Probleme. Ein Skill in .claude/skills/ gehört zu einem Repository. Sie haben acht Repositories. Der Skill wird also achtmal kopiert.

Das Frontmatter hilft dabei nicht. Die Agent Skills-Spezifikation erlaubt sechs Schlüssel. Die Distributionspfade, die diese Vorgabe erzwingen, geben die Liste aus, wenn Sie einen anderen Schlüssel verwenden:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Beachten Sie, was fehlt: Es gibt keinen Schlüssel version. In der Datei ist nicht festgehalten, welche Kopie neuer ist. Das ist sinnvoll, weil ein Skill ein Dokument und kein Paket ist. Die Versionierung muss deshalb aus der Ebene um die Datei herum kommen. Diese Ebene müssen Sie selbst verwalten.

Problem 1: Acht Kopien, die unbemerkt auseinanderlaufen

Copy-and-paste funktioniert am ersten Tag. Am sechzigsten Tag nicht mehr. Jemand korrigiert eine falsche Anweisung im Repository payments und ändert die anderen sieben nicht. Jemand anderes ergänzt in orders eine Regel zur Seitennummerierung. Nun führt derselbe Skill-Name zu zwei unterschiedlichen Reviews, je nachdem, in welchem Verzeichnis der Agent gestartet wurde. Keiner der beiden Entwickler weiß davon.

Der Fehler bleibt unbemerkt, weil kein Fehlerstatus vorhanden ist. Ein Skill besteht aus Prosa. Eine veraltete Anweisung erzeugt eine selbstsichere, falsche Antwort. Das ist die kostspielige Variante. Der Agent vergleicht Ihre Kopie nicht mit den Kopien anderer. Das einzige Signal ist daher eine Person, die bemerkt, dass zwei Repositories voneinander abweichen.

Problem zwei: Nichts pinnt eine Version

Selbst wenn ein Team seine Skills an einer Stelle verwaltet, erfolgt die Weitergabe meist über einen Kopierschritt: ein Setup-Skript, eine curl-Zeile in der Onboarding-Dokumentation oder ein Shell-Alias, das ein Verzeichnis synchronisiert. All diese Methoden installieren den Stand, der sich gerade an der Spitze des Branches befindet.

Dadurch können zwei Entwickler beim gleichen Commit derselben Anwendung unterschiedliche Anweisungen verwenden, wenn sie die Synchronisierung an unterschiedlichen Tagen ausgeführt haben. Außerdem lässt sich die entscheidende Frage nach einem fehlerhaften Agent-Lauf nicht beantworten: Welche Version des Skills hat diesen Lauf erzeugt? Ohne aufgezeichnete Revision ist der Lauf nicht reproduzierbar. Der Fehlerbericht lässt sich dann nicht sinnvoll bearbeiten.

Problem drei: Niemand weiß, ob der Skill noch funktioniert

Ein Skill hat keinen Compiler. Er besteht aus Anweisungen für ein Modell und kann daher ausfallen, obwohl die Datei Byte für Byte identisch bleibt. Ein Modell-Upgrade verändert, wie genau ein Modell lange Anweisungen befolgt. Ein Kommandozeilentool, das der Skill aufruft, benennt ein Flag um. Eine URL in einer Referenzdatei liefert plötzlich 404, und der Agent arbeitet mit der Fehlerseite.

In keinem dieser Fälle tritt der Fehler deutlich hervor. Der Agent antwortet weiterhin. Die Antwort ist nur schlechter als im letzten Monat. Das lässt sich nur schwer bemerken, wenn jede einzelne Pull-Anfrage kleine Änderungen enthält.

Was die Tools im Jahr 2026 lösen

Mehrere Lösungen sind derzeit verfügbar. Sie unterscheiden sich darin, wo die Version gespeichert wird.

Sperrdateien. Das skills-Befehlszeilentool von Vercel Labs (vercel-labs/skills, MIT-lizenziert, v1.7.2 am 9. Oktober 2026) installiert Skills aus einem git-Repository in dem Verzeichnis, das Ihr Agent erwartet. Es kennt die Verzeichnisstruktur von mehr als siebzig Agents. npx skills add <repo> installiert, npx skills update aktualisiert und npx skills list zeigt die vorhandenen Skills an. Das Tool verwaltet zwei Sperrdateien. Eine globale Datei unter ~/.agents/.skill-lock.json erfasst, welche Skills ein Benutzer installiert hat. Seit v1.4.1 (20. Februar 2026) schreibt die Installation im Projektbereich außerdem skills-lock.json in das Projektstammverzeichnis. Der Quellcode des Tools gibt an, dass diese Datei in die Versionsverwaltung übernommen werden soll. npx skills experimental_install stellt die Skills eines Projekts daraus wieder her. Issue 283 forderte einen skills install-Befehl, um die globale Sperrdatei auf einem anderen Rechner wiederherzustellen. Das Issue wurde am 5. November 2026 als nicht vorgesehen geschlossen. Der Maintainer bezeichnet es als dieselbe Anfrage wie Issue 549. Lesen Sie beide Issues als Statusbericht. Die Sperrdatei pro Projekt existiert. Der Befehl, der Skills daraus wiederherstellt, ist in der veröffentlichten Version v1.7.6 weiterhin als experimentell gekennzeichnet. Der Haupt-Branch des Projekts unterstützt inzwischen außerdem npx skills install ohne Quelle zum Wiederherstellen der Projektsperrdatei.

Spezifikationen und Tests. SkillSpec verfolgt den anderen Ansatz. Es behandelt einen SKILL.md als zu prüfenden Vertrag und nicht als Text, dem man vertrauen muss. Das erklärte Ziel ist, Skills „nachvollziehbar, testbar und beweisbar“ zu machen. skillspec doctor <path> zeigt, an welcher Stelle ein Agent den Zusammenhang wahrscheinlich verliert. skillspec boundary map <path> zeigt den Inhalt des Skills. skillspec boundary assess <path> meldet, welche Ressourcen er erreichen kann, nach Risiko geordnet. Es handelt sich um ein Rust-Crate mit einer dualen MIT- oder Apache-2.0-Lizenz. Version 0.2.2 wurde am 29. Juli 2026 veröffentlicht und ist am 10. Oktober 2026 weiterhin die neueste Version auf crates.io. Installieren Sie statt der neuesten Version die festgelegte Version:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked wird mit den Abhängigkeitsversionen erstellt, mit denen das Crate veröffentlicht wurde. Dadurch ändert sich die Build-Umgebung nicht unbemerkt. skillspec --version sollte 0.2.2 ausgeben. Eine andere Zahl bedeutet, dass eine ältere Binärdatei weiter vorn in Ihrem PATH gefunden wird.

Praxis der Anbieter. Google hat in einem Beitrag zu Aufbau, Tests und Skalierung von Agent-Skills beschrieben, wie die Skills in google/skills erstellt werden. Abgesehen vom Umfang ist der Mechanismus gewöhnliche kontinuierliche Integration (CI). Vor dem Merge durchläuft jeder Skill Linter für Frontmatter-Metadaten, Zeilenanzahl, Verzeichnisstruktur und Benennung. Ein Link-Checker schlägt beim Build fehl, sobald eine URL den Status 404 zurückgibt. Dadurch werden plausibel wirkende Links erkannt, die ein Agent erfunden hat. Autoren müssen zusammen mit dem Skill eine Suite von Evaluierungs-Prompts und eine Bewertungsrichtlinie bereitstellen. Geplante Evaluierungsjobs werden anschließend wöchentlich für die gesamte Bibliothek ausgeführt, um Regressionen zu erkennen. Jeder Skill hat außerdem einen benannten Verantwortlichen, der bei sinkender Qualität Korrekturen vornehmen soll.

Das Muster hinter allen drei Antworten

Sie müssen sich für keine dieser Antworten entscheiden. Dahinter steht ein einheitliches Muster, und mit einfachem git erhalten Sie alles, was Sie dafür brauchen.

1. Eine einzige Quelle der Wahrheit. Jede Skill-Datei hat genau einen zentralen Ablageort. Jedes Repository verweist auf diesen Ablageort, statt eine Kopie zu speichern.
2. Eine festgelegte Version pro Repository. Jedes Projekt speichert die exakt verwendete Revision. Ein Upgrade ist dadurch ein Commit in diesem Projekt, einschließlich Autor und Datum.
3. Ein Smoke-Test pro Skill. Eine ausführbare Prüfung bestätigt, dass der Skill weiterhin das zugesagte Ergebnis liefert.
4. Ein Review-Prozess. Eine Änderung an einem gemeinsam verwendeten Skill wird geprüft. Jeder Verwender sieht vor der Übernahme einen Diff.

Das entspricht der Struktur einer Abhängigkeit. Skills wurden schneller zu gemeinsam verwendeten Artefakten, als sich die passenden Werkzeuge entwickeln konnten. Deshalb ist es am sichersten, auf die Werkzeuge zurückzugreifen, denen Sie bereits vertrauen.

Ein Aufbau für ein kleines Team auf einem selbst gehosteten Git-Remote

Ein Repository enthält die Skills. Nichts anderes liegt darin. Dadurch entspricht seine Historie einem Änderungsprotokoll der Anleitungen.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Releases werden durch Tags gekennzeichnet. Verwenden Sie annotierte Tags, da sie eine Nachricht und ein Datum enthalten. Formulieren Sie die Nachricht als Begründung, warum ein Consumer das Update benötigt:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Wenn Ihr Remote Gitea, Forgejo oder GitLab ist oder Sie ein Bare-Repository über SSH auf Ihrem eigenen VPS verwenden, ändert sich an den folgenden Schritten nichts. Es handelt sich vollständig um Git und einen symbolischen Link.

Pinning mit einem git submodule

Ein Submodul zeichnet genau einen Commit eines anderen Repositorys in Ihrem Repository auf. Dieser Eintrag ist die feste Version. In jedem Projekt, das es verwendet:

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"

Der symbolische Link macht dies möglich. Ein Skill-Eintrag auf Projektebene kann ein symbolischer Link auf ein Verzeichnis an einer anderen Stelle auf dem Datenträger sein. Claude Code folgt diesem Link und liest SKILL.md aus dem Zielverzeichnis. Der Skill wird daher wie ein normaler Projekt-Skill geladen, während die Dateien im Submodul unter dem von Ihnen ausgewählten Commit liegen.

Prüfen Sie die festgelegte Version:

git submodule status

Eine korrekte Zeile beginnt mit einem Leerzeichen, gefolgt vom Commit, dem Pfad und dem nächstgelegenen Tag:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Ein führendes - bedeutet, dass das Submodul noch nicht initialisiert wurde. .claude/skills/api-review verweist daher auf nichts, und der Skill wird stillschweigend nicht geladen. Beheben Sie das mit git submodule update --init. Ein führendes + bedeutet, dass der ausgecheckte Commit vom aufgezeichneten Commit abweicht. Dieser Entwickler verwendet dann Anweisungen, die sonst niemand verwendet. Neue Klone benötigen git clone --recurse-submodules. Diese Zeile gehört in die README, weil ein normaler Klon vendor/agent-skills leer lässt und keinen Fehler ausgibt.

Ein Upgrade erfolgt bewusst. Genau das ist der Zweck:

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"

Die Zeile diff ist der Prüfpfad. Sie zeigt dieselbe Änderung, die jedes andere verwendende Repository ebenfalls erhält, und passt in einen Pull Request.

Stattdessen Pinning mit einem Plugin-Marketplace

Wenn Sie nicht jeden Entwickler mit Submodulen vertraut machen möchten, übernimmt das Claude-Code-Plugin-System die Verteilung für Sie und funktioniert mit einem selbst gehosteten Remote. Legen Sie im Skills-Repository unter .claude-plugin/marketplace.json einen Katalog ab:

{
  "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"
      }
    }
  ]
}

Hier sind zwei unterschiedliche Quellen beteiligt. Ihre Verwechslung ist der häufigste Fehler. Die Marketplace-Quelle gibt an, von wo der Katalog selbst abgerufen wird. Sie akzeptiert ref für einen Branch oder ein Tag, aber nicht sha. Eine Plugin-Quelle innerhalb des Katalogs akzeptiert beide Angaben. Wenn beide gesetzt sind, ist sha der tatsächlich verwendete Pin. Der Pin auf einen exakten Commit gehört daher in den Katalogeintrag. Auch die Typbezeichnungen unterscheiden sich. Innerhalb des Katalogs bezeichnet url ein zu klonendes Git-Repository. In einer Marketplace-Quelle bezeichnet url einen direkten Link zu einer marketplace.json-Datei. Ein Git-Repository wird dort mit git angegeben.

Jedes Repository, das das Plugin verwendet, trägt den Marketplace anschließend in seiner versionierten .claude/settings.json ein:

{
  "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 registriert den Marketplace für einen Teamkollegen, sobald dieser den Dialog zur Vertrauensstellung des Arbeitsbereichs für den Projektordner bestätigt. Eine Wiki-Seite mit entsprechenden Anweisungen ist dafür nicht erforderlich. Der Katalogeintrag verweist auf eine Git-URL und nicht auf einen relativen Pfad. Daher wird das Plugin nicht allein aus den Einstellungen des Repositorys installiert. Jeder Teamkollege führt claude plugin install team-skills@acme-agents --scope project einmal aus. Bis dahin meldet Claude Code, dass das Plugin in den Projekteinstellungen aktiviert, aber nicht installiert ist. Die Skills sind anschließend unter /team-skills:api-review verfügbar, weil Plugin-Skills durch den Plugin-Namen einen Namespace erhalten und nicht mit einem gleichnamigen Projekt-Skill kollidieren können. Nach dem Push eines neuen Tags aktualisieren die Benutzer den Marketplace mit /plugin marketplace update acme-agents. Anschließend führen sie /reload-plugins aus, wenn die Installationszusammenfassung dazu auffordert.

Einen Smoke-Test für einen Skill schreiben

Ein Smoke-Test ist ein skriptgesteuerter Agent-Lauf gegen ein Fixture mit einem bekannten Fehler sowie einer Assertion. Claude Code läuft mit -p nicht interaktiv, und ein vom Benutzer aufgerufener Skill funktioniert dort: Fügen Sie /skill-name in die Prompt-Zeichenfolge ein. Sie wird vor dem Start des Laufs expandiert.

#!/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 ist eine kurze Datei mit genau einem absichtlich eingebauten Fehler. Die Assertion prüft, ob der Skill ihn benennt. jq -e beendet sich mit einem Fehlercode, wenn sein Filter null erzeugt. Ein Skill, der den eingebauten Fehler nicht mehr erkennt, lässt das Skript daher fehlschlagen. claude selbst beendet sich mit einem Fehlercode, wenn der Lauf fehlschlägt. set -euo pipefail wandelt beide Fehler in einen fehlgeschlagenen Test um.

Ein Modell formuliert seine Antworten zwischen den Läufen unterschiedlich. Prüfen Sie daher niemals einen vollständigen Satz. Prüfen Sie stattdessen einen Bezeichner, den der Skill ausgeben soll, oder ein Feld eines von Ihnen vorgegebenen Schemas. Halten Sie das Fixture klein, damit der Lauf kostengünstig bleibt.

Fügen Sie in CI --bare hinzu. Ohne diese Option lädt claude -p denselben Kontext wie eine interaktive Sitzung. Dazu gehören Hooks, Plugins und CLAUDE.md von dem Rechner, auf dem der Lauf ausgeführt wird. Dadurch kann die persönliche Konfiguration eines Teammitglieds das Ergebnis verändern. Der Bare-Modus überspringt die automatische Erkennung, mit Ausnahme von Skills in .claude/skills/ unter einem Verzeichnis, das ausdrücklich mit --add-dir angegeben wurde. Den Projekt-Skill, den Sie hier testen, überspringt er daher. Laden Sie diesen Skill explizit. Der Bare-Modus liest auch Ihre Subscription-Anmeldung nicht. Setzen Sie daher zuerst ANTHROPIC_API_KEY in der Umgebung:

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

Ein mit --plugin-dir geladenes Plugin übernimmt seinen Namen aus .claude-plugin/plugin.json. Ohne dieses Manifest wird es nach seinem Verzeichnis benannt. Legen Sie ein plugin.json mit "name": "team-skills" neben dem Katalog im Skills-Repository ab. Andernfalls muss der obige Befehl stattdessen /agent-skills:api-review aufrufen.

Mit --output-format stream-json meldet das system/init-Ereignis, welche Plugins geladen wurden. Für nicht geladene Plugins enthält es ein plugin_errors-Array. Das Ereignis öffnet den Stream, sofern nicht zuerst Startup-Ereignisse eintreffen. Lassen Sie den CI-Job bei einem nicht leeren plugin_errors fehlschlagen. Dadurch wird erkannt, wenn ein Pin auf eine nicht mehr vorhandene Revision verweist. Andernfalls würde der Agent Ihre internen Regeln einfach stillschweigend ignorieren.

Eine gemeinsam genutzte Fähigkeit ist eine ausführbare Anweisung

Zwei Funktionen machen das wörtlich möglich. Beide sind relevant, wenn die Datei von einem anderen Team stammt.

Erstens kann ein SKILL.md Shell-Befehle ausführen, bevor das Modell irgendetwas liest. Eine solche Zeile im Textkörper ist eine Vorverarbeitung:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

Der Befehl wird auf dem Rechner ausgeführt, der die Fähigkeit lädt. Seine Ausgabe ersetzt den Platzhalter im Text, den das Modell erhält. Ein umzäunter Block, der mit drei Backticks gefolgt von ! beginnt, führt mehrere Befehle auf dieselbe Weise aus. Zur Laufzeit wird dafür keine Bestätigung angefordert. Claude Code prüft jeden Befehl anhand Ihrer Berechtigungsregeln. Außerhalb des automatischen Modus bricht ein Befehl, den diese Regeln nicht erlauben, die Fähigkeit ab, sofern die Fähigkeit ihn nicht über die zweite Funktion vorab freigibt. Regeln zum Ablehnen und Nachfragen setzen diese Vorabfreigabe weiterhin außer Kraft. Eine gemeinsam genutzte Fähigkeit zu lesen bedeutet daher auch, ihre Befehlssubstitutionen zu lesen.

Zweitens können Frontmatter-Angaben Tools vorab freigeben. allowed-tools gewährt die aufgeführten Tools für den Aufruf, der die Fähigkeit gestartet hat, ohne Berechtigungsabfrage. Workspace-Vertrauen begrenzt diese Freigabe nicht: Claude Code wendet allowed-tools einer Projektfähigkeit auch in einem -p an, das in einem Ordner ausgeführt wird, dem niemand vertraut hat. Die Claude-Code-Dokumentation beschreibt die Folge eindeutig: Eine Fähigkeit kann sich selbst weitreichenden Tool-Zugriff gewähren. Prüfen Sie daher den allowed-tools von Fähigkeiten, die in einem Repository versioniert sind, bevor Sie Claude Code dort ausführen. Eine Organisation kann Projekt- und persönlichen Fähigkeiten das Feld entziehen, indem sie in verwalteten Einstellungen allowManagedPermissionRulesOnly setzt. Dafür ist Claude Code v2.1.282 oder höher erforderlich.

Behandeln Sie eine Aktualisierung einer Fähigkeit daher genau wie die Aktualisierung einer Abhängigkeit. Fixieren Sie die Version nach Möglichkeit auf einen exakten Commit, weil ein Tag verschoben werden kann und sich ein Branch definitionsgemäß weiterbewegt. Auf einem eingeschränkten Rechner ersetzt "disableSkillShellExecution": true in den Einstellungen jede Befehlssubstitution durch den Literaltext [shell command execution disabled by policy], statt sie auszuführen. Wird diese Einstellung über verwaltete Einstellungen angewendet, kann ein Benutzer sie nicht überschreiben. Gebündelte und verwaltete Fähigkeiten sind von dieser Einstellung ausgenommen.

Dieselbe Sorgfalt gilt für die Daten, die eine Fähigkeit liest. Eine Fähigkeit, die env ausführt oder eine Konfigurationsdatei öffnet, übernimmt alles Gefundene in den Kontext des Modells. Das ist der Fehler, der unter Geheimnisse aus den von Ihnen ausgeführten Agenten heraushalten beschrieben wird. Eine Fähigkeit, die eine Seite abruft oder eine Abfrage ausführt, richtet dieselbe Offenlegung nach außen. Der abgerufene Text landet im Kontext und sieht dort genau wie die von Ihnen geschriebenen Anweisungen aus. Diese Grenze sollten Sie verstehen, bevor Sie einen Agenten für die Websuche auf Ihre eigene SearXNG-Instanz verweisen.

Was Sie bei einer Versionsaktualisierung lesen sollten

• Das Diff jedes SKILL.md-Inhalts, weil dieser Text die Anweisung enthält, die Ihr Agent befolgt.
• Jede Befehlssubstitution, weil sie beim Laden des Skills auf Ihrem Rechner ausgeführt wird.
• Jede Änderung an allowed-tools, weil diese Zeile Tools ohne Rückfrage freigibt.
• Den Testlauf hinter dem Tag. Wenn das gemeinsam genutzte Repository eigene Smoke-Tests in CI ausführt, sollte der Tag, auf den Sie verweisen, einen erfolgreichen Lauf aufweisen.

Ein Reviewer, der das gesamte Diff nicht innerhalb von zehn Minuten lesen kann, betrachtet einen Skill, der zu groß geworden ist. Teilen Sie ihn auf. Dasselbe gilt für die Repository-Dokumente, die Ihre Agents lesen: Halten Sie dauerhafte Regeln in den Dateien aus der Aufteilung in AGENTS.md und HUMAN.md fest, bewahren Sie architektonische Überlegungen in einer für Agents geschriebenen DESIGN.md auf, und beschränken Sie Skills auf klar abgegrenzte Verfahren.

Wenn eine Modell- oder Tooländerung einen Skill beschädigt

Unterhalb eines Skills können sich mehrere Dinge ändern, ohne dass jemand ihn bearbeitet. Ein Modellupgrade verändert, wie zuverlässig eine lange Anweisung befolgt wird. Dadurch erreicht ein Skill, der darauf angewiesen war, dass das Modell Schritt neun ausführt, diesen Schritt möglicherweise nicht mehr. Ein Kommandozeilentool benennt ein Flag um. Der Agent verwendet dann das alte Flag, liest die Fehlermeldung und improvisiert. Eine referenzierte URL liefert plötzlich 404 zurück. Ein Agent-Harness ändert die Auswahl der Skills. Dadurch gewinnt ein description, das zuvor den Treffer erzielt hat, möglicherweise nicht mehr. Wenn eine Prozedur deshalb vorzeitig endet, behebt kein Versionssprung das Problem. Die Anweisungen selbst benötigen dann eine Struktur, die die letzten Schritte erzwingt. Darauf basiert der unlazy-Skill und seine Depth-Tree-Methode.

Deshalb ist der Smoke-Test in diesem Aufbau so wichtig. Führen Sie den Test jedes Skills nach einem Zeitplan sowie bei jedem Push aus. Google führt seine Evaluierungsjobs aus diesem Grund wöchentlich für die gesamte Bibliothek aus. Für ein Team mit zehn Skills reicht ein wöchentlicher Cronjob auf einem kleinen VPS aus. Nur so erfahren Sie von dem Problem, bevor es ein Entwickler bemerkt.

Auch die Portabilität hilft. Die Agent-Skills-Spezifikation beschränkt das Frontmatter auf sechs Schlüssel. Ein nach dieser Spezifikation geschriebener Skill kann dadurch in anderen Tools geladen werden, nicht nur in dem Tool, für das Sie ihn geschrieben haben. Jeder zusätzliche, harness-spezifische Schlüssel ist dagegen eine Wette auf einen einzelnen Anbieter. Skills zu schreiben, die einen Modellwechsel überstehen, ist eine eigene Disziplin. Sie wird in einen Skill für jedes Modell portierbar machen behandelt.

FAQ

Wie kann ich eine Agent-Fähigkeit über mehrere Repositorys hinweg gemeinsam verwenden?

Legen Sie die Fähigkeit in einem dedizierten Git-Repository ab, markieren Sie darin Releases mit Tags, und lassen Sie jedes nutzende Projekt auf einen Tag verweisen, statt die Datei zu kopieren. Dafür eignen sich zwei Mechanismen. Ein Git-Submodul speichert einen exakten Commit. Ein Symlink von .claude/skills/<name> in das Submodul sorgt dafür, dass die Datei als normale Projektfähigkeit geladen wird. Ein Plugin-Marktplatz erfüllt dieselbe Aufgabe über /plugin. Die Version wird dabei im .claude/settings.json des nutzenden Repositorys festgelegt. Beide Varianten speichern die Version in der Git-Historie. Dadurch können Sie nachvollziehen, welche Anweisungen einen bestimmten Agent-Lauf erzeugt haben.

Kann ich eine Agent-Fähigkeit auf eine bestimmte Version festlegen?

Nicht innerhalb von SKILL.md, weil dieses Frontmatter keinen Schlüssel version enthält. Die Festlegung muss aus der übergeordneten Ebene der Datei kommen. Ein Git-Submodul legt konstruktionsbedingt einen exakten Commit fest. In einem Claude-Code-Plugin-Marktplatz akzeptiert eine Plugin-Quelle ref für einen Branch oder Tag und sha für einen exakten Commit. Wenn beide vorhanden sind, hat sha Vorrang. Die Marktplatzquelle selbst akzeptiert nur ref. Bevorzugen Sie die Festlegung auf einen Commit, weil ein Tag nach der Prüfung verschoben werden kann.

Was sollte ein Smoke-Test für eine Fähigkeit prüfen?

Prüfen Sie etwas, das stabil bleibt. Führen Sie die Fähigkeit nicht interaktiv mit einem Fixture aus, das einen bekannten Fehler enthält. Prüfen Sie anschließend, ob eine bestimmte Kennung in der Ausgabe erscheint, zum Beispiel die Regel-ID, die die Fähigkeit melden soll. Fordern Sie mit --output-format json und --json-schema eine strukturierte Ausgabe an, damit die Prüfung exakt ist. jq -e lässt das Skript fehlschlagen, wenn der Wert fehlt. Prüfen Sie niemals einen vollständigen Satz. Ein Modell formuliert seine Antworten zwischen verschiedenen Läufen um.

Ist es sicher, eine gemeinsam verwendete Fähigkeit aus dem Repository eines anderen Teams zu installieren?

Behandeln Sie sie wie eine Codeabhängigkeit, weil sie ausführbare Anweisungen enthält. Eine SKILL.md kann beim Laden über die Befehlssubstitutionsform ! Shell-Befehle ausführen. Das Frontmatter-Feld allowed-tools kann Tools ohne Rückfrage vorab freigeben. Lesen Sie bei jeder Aktualisierung den Diff, legen Sie einen exakten Commit statt eines Branches fest, und bevorzugen Sie eine Quelle, die Ihr eigenes Team kontrolliert. Auf verwalteten Rechnern verhindert "disableSkillShellExecution": true in den Einstellungen, dass Befehlssubstitutionen in Benutzer-, Projekt-, Plugin- und Fähigkeiten aus zusätzlichen Verzeichnissen ausgeführt werden. Gebündelte und verwaltete Fähigkeiten sind davon ausgenommen.

Funktioniert eine gemeinsam verwendete Fähigkeit auch in Agents außerhalb von Claude Code?

Das hängt davon ab, welches Frontmatter Sie verwenden. Die Agent-Skills-Spezifikation definiert sechs Schlüssel: name, description, license, compatibility, metadata und allowed-tools. Eine Fähigkeit, die auf diese Schlüssel beschränkt ist, wird von Tools geladen, die die Spezifikation implementieren. Sie wird außerdem ohne Änderungen in Claude Code geladen. Harness-spezifische Schlüssel und Body-Funktionen außerhalb der Spezifikation werden an anderer Stelle ignoriert oder abgelehnt. Lassen Sie sie daher aus jeder Fähigkeit heraus, die Sie weitgehend gemeinsam verwenden möchten.