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 so wie eine 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 ohne externe Dienste aufbauen.

Ein Agent-Skill ist ein Ordner 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-Datei liegt und warum ihre gemeinsame Nutzung schwierig ist

Claude Code lädt Skills aus drei Verzeichnissen. Die Dokumentation zu Skills nennt jeden dieser Pfade.

• ~/.claude/skills/<skill-name>/SKILL.md ist benutzerbezogen. Der Inhalt wird in all Ihren Projekten geladen, aber in keinem Projekt anderer Benutzer.
• .claude/skills/<skill-name>/SKILL.md gilt auf Projektebene. Der Inhalt wird für jeden geladen, der dieses Repository auscheckt.
• <plugin>/skills/<skill-name>/SKILL.md wird mit einem Plugin ausgeliefert. Der Inhalt wird überall geladen, wo dieses Plugin aktiviert ist.

Der mittlere Pfad ist für ein Team am nützlichsten, weil er versioniert wird und jeder, der das Repository klont, die Datei erhält. Dort beginnen jedoch auch die Probleme. Eine Skill-Datei in .claude/skills/ gehört zu einem Repository. Sie haben acht Repositories. Daher wird die Skill-Datei achtmal kopiert.

Das Frontmatter hilft dabei nicht. Die Agent Skills-Spezifikation erlaubt sechs Schlüssel. Die Pfade für die Verteilung, 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 wird nicht festgehalten, welche Kopie neuer ist. Das ist nachvollziehbar, weil eine Skill-Datei ein Dokument und kein Paket ist. Die Versionierung muss daher 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.

Lockfiles. Das skills-Befehlszeilentool von Vercel Labs (vercel-labs/skills, MIT-lizenziert, Version 1.5.22 am 5. August 2026) installiert Skills aus einem Git-Repository in das Verzeichnis, das Ihr Agent erwartet. Es kennt das Layout von mehr als siebzig Agents. npx skills add <repo> installiert, npx skills update aktualisiert und npx skills list zeigt die vorhandenen Skills an. Die Liste der installierten Skills wird einmal pro Benutzer statt einmal pro Repository gespeichert. Eine offene Anfrage in diesem Projekt (Issue 283) fordert einen skills install-Befehl, der alle im Lockfile erfassten Skills erneut installiert. Damit erhält ein zweiter Rechner denselben Bestand. Diese Anfrage ist als Statusbericht zu verstehen. Das Lockfile-Konzept ist festgelegt. Die projektbezogene Umsetzung wird noch entwickelt.

Spezifikationen und Tests. SkillSpec verfolgt den anderen Ansatz. Ein SKILL.md wird als zu prüfender Vertrag behandelt und nicht als Text, dem man vertrauen muss. Das erklärte Ziel ist, Skills "befolgbar, testbar und nachweisbar" zu machen. skillspec doctor <path> meldet, an welchen Stellen ein Agent wahrscheinlich den Zusammenhang verliert. skillspec boundary map <path> meldet, worauf der Skill zugreifen kann. skillspec boundary assess <path> ordnet diese Ergebnisse nach Risiko. SkillSpec ist ein Rust-Crate mit dualer MIT- oder Apache-2.0-Lizenz und hatte am 29. Juli 2026 die Version 0.2.2. Installieren Sie die festgelegte Version und nicht die neueste:

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

--locked erstellt den Build mit den Abhängigkeitsversionen, mit denen das Crate veröffentlicht wurde. Dadurch ändern sich die Abhängigkeiten während des Builds nicht unerwartet. skillspec --version sollte 0.2.2 ausgeben. Eine andere Zahl bedeutet, dass eine ältere Binärdatei in Ihrem PATH Vorrang hat.

Praxis der Anbieter. Google beschreibt in einem Beitrag zu Entwicklung, Tests und Skalierung von Agent-Skills, wie die Skills in google/skills erstellt werden. Abgesehen von der Größenordnung handelt es sich um gewöhnliche kontinuierliche Integration (CI). Jeder Skill durchläuft vor dem Merge Linter-Prüfungen für Frontmatter-Metadaten, Zeilenanzahl, Verzeichnisstruktur und Benennung. Ein Linkprüfer lässt den Build bei jeder URL fehlschlagen, die 404 zurückgibt. Dadurch werden auch plausibel wirkende Links erkannt, die ein Agent erfunden hat. Autoren müssen zusammen mit dem Skill eine Suite von Evaluierungs-Prompts und ein Bewertungsraster bereitstellen. Geplante Evaluierungsjobs werden anschließend wöchentlich für die gesamte Bibliothek ausgeführt, um Regressionen zu erkennen. Außerdem hat jeder Skill einen namentlich benannten Verantwortlichen, der ihn bei sinkender Qualität korrigieren 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 über einen Plugin-Marktplatz

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 an:

{
  "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 verschiedene Quellen beteiligt. Ihre Verwechslung ist der häufigste Fehler. Die Marketplace-Quelle, also die Quelle, von der der Katalog selbst abgerufen wird, 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 das tatsächlich verwendete Pinning. Das Pinning auf einen exakten Commit gehört daher in den Katalogeintrag.

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

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

Ein Teammitglied, das dem Projektordner vertraut, wird zur Installation des Marktplatzes aufgefordert. Das Plugin wird anschließend aktiviert, ohne dass eine Wiki-Seite die erforderlichen Schritte beschreiben muss. Die Skills sind dann unter /team-skills:api-review verfügbar, weil Plugin-Skills nach dem Plugin-Namen namespaced sind und nicht mit einem gleichnamigen Projekt-Skill kollidieren können. Nachdem Sie ein neues Tag gepusht haben, aktualisieren die Verbraucher mit /plugin marketplace update acme-agents. Führen Sie anschließend /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 eine Fixture mit einem bekannten Fehler sowie einer Assertion. Claude Code wird mit -p nicht interaktiv ausgeführt. Ein vom Benutzer aufgerufener Skill funktioniert dort: Setzen Sie /skill-name in den Prompt-String. Der String 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 einem absichtlich eingebauten Fehler. Die Assertion prüft, ob der Skill diesen Fehler nennt. jq -e beendet sich mit einem Exit-Code ungleich 0, wenn sein Filter null erzeugt. Ein Skill, der den eingebauten Fehler nicht mehr erkennt, lässt das Skript daher fehlschlagen. claude beendet sich selbst mit einem Exit-Code ungleich 0, wenn der Lauf fehlschlägt. set -euo pipefail wandelt einen der beiden Fehler in einen fehlgeschlagenen Test um.

Ein Modell formuliert seine Antworten zwischen den Läufen unterschiedlich. Prüfen Sie daher niemals auf einen vollständigen Satz. Prüfen Sie stattdessen auf einen Bezeichner, den der Skill ausgeben soll, oder auf ein Feld eines von Ihnen vorgegebenen Schemas. Halten Sie die 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 vom System, 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. Dadurch wird auch der getestete Skill übersprungen. Laden Sie diesen Skill daher explizit. Der Bare-Modus liest außerdem Ihre Subscription-Anmeldung nicht ein. Setzen Sie deshalb 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

Mit --output-format stream-json meldet das erste Ereignis des Laufs, welche Plugins geladen wurden. Es enthält außerdem ein plugin_errors-Array für die Plugins, die nicht geladen wurden. Lassen Sie den CI-Job bei einem nicht leeren plugin_errors fehlschlagen. Dadurch wird ein Pin erkannt, der auf eine nicht mehr vorhandene Revision verweist. Andernfalls kann dies so aussehen, als würde der Agent Ihre projektspezifischen Regeln stillschweigend ignorieren.

Ein gemeinsam genutzter Skill ist eine ausführbare Anweisung

Zwei Funktionen machen das wörtlich relevant. Das gilt besonders, 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 den Skill lädt. Seine Ausgabe ersetzt den Platzhalter im Text, den das Modell erhält. Ein mit drei Backticks begonnener Block gefolgt von ! führt mehrere Befehle auf dieselbe Weise aus. Zur Laufzeit bestätigt niemand diese Vorgänge. Einen gemeinsam genutzten Skill zu lesen bedeutet daher, auch seine Befehlssubstitutionen zu lesen.

Zweitens kann das Frontmatter Tools vorab freigeben. allowed-tools gewährt die aufgeführten Tools ohne Berechtigungsabfrage für den Durchlauf, in dem der Skill aufgerufen wurde. Bei einem Projektskill wird diese Freigabe wirksam, sobald jemand den Dialog zur Bestätigung des Workspace-Vertrauens für den Ordner akzeptiert. Die Dokumentation von Claude Code beschreibt die Folge eindeutig: Prüfen Sie Projektskills, bevor Sie einem Repository vertrauen, weil ein Skill sich selbst weitreichenden Tool-Zugriff gewähren kann.

Behandeln Sie eine Aktualisierung eines Skills daher genau wie eine Aktualisierung einer Abhängigkeit. Verwenden Sie, sofern der Mechanismus dies zulässt, einen exakten Commit als Fixierung, weil ein Tag verschoben werden kann und sich ein Branch definitionsgemäß weiterbewegt. Auf einem abgesicherten Rechner ersetzt "disableSkillShellExecution": true in den Einstellungen jede Befehlssubstitution durch den Literaltext [shell command execution disabled by policy], anstatt sie auszuführen. Wird diese Einstellung über verwaltete Einstellungen angewendet, kann der Benutzer sie nicht überschreiben. Gebündelte und verwaltete Skills sind von dieser Einstellung ausgenommen.

Dieselbe Sorgfalt gilt für die Daten, die ein Skill liest. Ein Skill, der env ausführt oder eine Konfigurationsdatei öffnet, übernimmt alles, was er dort findet, in den Kontext des Modells. Das ist der Fehler, der in Geheimnisse aus den von Ihnen ausgeführten Agents heraushalten behandelt wird. Ein Skill, der eine Seite abruft oder eine Abfrage ausführt, verlagert dieselbe Offenlegung nach außen, weil der abgerufene Text im Kontext genau wie die von Ihnen verfassten Anweisungen erscheint. Diese Grenze sollten Sie kennen, bevor Sie einen Agent 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 nutzen?

Legen Sie die Fähigkeit in einem eigenen git-Repository ab, markieren Sie darin Releases mit Tags, und lassen Sie jedes verwendende Projekt auf einen Tag verweisen, statt die Datei zu kopieren. Dafür gibt es zwei geeignete Mechanismen. Ein git submodule speichert einen exakten Commit, und ein Symlink von .claude/skills/<name> in das Submodul sorgt dafür, dass die Fähigkeit als normale Projektfähigkeit geladen wird. Ein Plugin-Marktplatz erfüllt dieselbe Aufgabe über /plugin, wobei die Version im .claude/settings.json des verwendenden Repositorys festgelegt wird. In beiden Fällen steht 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 besitzt. Die Festlegung muss aus der umgebenden Ebene kommen. Ein git submodule 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 Ihrer Prüfung verschoben werden kann.

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

Prüfen Sie auf etwas Stabileres. Führen Sie die Fähigkeit nicht interaktiv mit einer Fixture aus, die einen bekannten Fehler enthält. Prüfen Sie anschließend, ob eine bestimmte Kennung in der Ausgabe erscheint, beispielsweise die ID einer Regel, die die Fähigkeit melden soll. Eine strukturierte Ausgabe mit --output-format json und --json-schema macht die Prüfung exakt, und jq -e lässt das Skript fehlschlagen, wenn der Wert fehlt. Prüfen Sie niemals einen vollständigen Satz, weil ein Modell seine Antworten zwischen den Läufen unterschiedlich formuliert.

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

Behandeln Sie sie wie eine Code-Abhängigkeit, weil sie ausführbare Anweisungen enthält. Ein SKILL.md kann beim Laden über die Befehlsersetzungsform ! Shell-Befehle ausführen. Das Frontmatter-Feld allowed-tools kann Werkzeuge ohne Rückfrage vorab freigeben. Lesen Sie bei jeder Aktualisierung das 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 die Ausführung von Befehlsersetzungen vollständig.

Funktioniert eine gemeinsam genutzte Fähigkeit auch in Agents außer 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 allen Werkzeugen geladen, die die Spezifikation implementieren. Sie wird auch in Claude Code ohne Änderungen geladen. Harness-spezifische Schlüssel und zusätzliche Funktionen im Inhalt werden an anderer Stelle ignoriert oder abgelehnt. Lassen Sie sie daher aus jeder Fähigkeit weg, die Sie umfassend gemeinsam nutzen möchten.