Claude Code Plugin testen: Native Evals als Release-Gate

Der Zeitpunkt ist entscheidend. Claude Code 2.1.269 hat Plugin-Evals am 11. September 2026 eingeführt. Das bislang maßgebliche Tutorial mit Datumsangabe zu dieser Suchanfrage beschreibt noch einen eigenen Python-Runner. Wer heute ein lokales Plugin betreut, kommt nun auf direktem Weg ans Ziel: einen Verhaltensfall anlegen, ihn gegen eine Kontrollgruppe ausführen, den Bericht prüfen und anschließend genau die absichtlich erzeugte Regression in CI blockieren.

Was ein nativer Eval tatsächlich misst

Ein Plugin-Eval ist ein A/B-Test für Agentenverhalten. Man kann sich zwei identische Werkstätten vorstellen, die denselben Arbeitsauftrag erhalten. In einer ist das Plugin installiert, in der anderen nicht. Claude Code wiederholt die Aufgabe in beiden, bewertet die Arbeit und meldet WITH, W/OUT und Δ – also den Score mit Plugin, den Score ohne Plugin und die Differenz zwischen beiden.

Dieses Delta ist die entscheidende Kennzahl. Ein Score von 1.0 in beiden Varianten wirkt zwar ausgezeichnet, zeigt aber nur, dass Claude die Aufgabe bereits ohne das Plugin lösen konnte. Ein positives Delta belegt einen messbaren Beitrag. Ein negatives Delta bedeutet, dass das Plugin das getestete Verhalten verschlechtert hat.

Standardmäßig erzeugt ein einzelner Fall drei neue Sitzungen mit Plugin und drei ohne. Jede Sitzung erhält ein isoliertes Home-Verzeichnis, Arbeitsverzeichnis und eine eigene Claude-Code-Konfiguration. Persönliche Einstellungen, die CLAUDE.md des Projekts, andere Plugins, Memory und persönliche MCP-Server werden nicht übernommen. Diese Isolation macht den Vergleich sauberer. Sie sorgt zugleich dafür, dass ein Plugin, das heimlich von der eigenen Laptop-Konfiguration abhängt, aus dem richtigen Grund scheitert. Die Dokumentation von Anthropic zu Plugin-Evals beschreibt den vollständigen Isolations- und Sicherheitsrahmen.

Mit einem funktionierenden lokalen Plugin beginnen

Verhaltens-Evals sind die zweite Prüfung, nicht die erste. Das Plugin-Verzeichnis benötigt eine plugin.json, eine .claude-plugin/plugin.json oder eine gültige Struktur für ein Skills-Verzeichnis. claude plugin validate findet Datei- und Schemafehler. claude plugin eval beantwortet dagegen Fragen wie: „Wurde der Skill bei einer natürlichen Anfrage ausgelöst und hat er das vorgesehene Teamformat geliefert?“

Erforderlich sind außerdem Claude Code v2.1.269 oder neuer sowie dieselbe Authentifizierung wie für gewöhnliche Sitzungen. Eval-Sitzungen, Judge-Grader und die interaktive Initialisierung belasten das Tarifkontingent oder die API-Abrechnung. Ist die allgemeine Claude-Code-Einrichtung noch neu, empfiehlt sich vor einem Release-Gate zunächst der grundlegende lokale Workflow.

Im Stammverzeichnis eines vertrauenswürdigen Plugins werden zunächst die Version geprüft und ein leerer Fall angelegt:

claude --version
claude plugin eval init --bare release-note

Die interaktive Alternative lautet claude plugin eval init. Sie liest das Plugin, fragt nach den Merkmalen eines guten Ergebnisses, schlägt Fälle und Grader vor, testet sie einmal und schreibt anschließend die Suite. Um den Aufbau zu verstehen, eignet sich der Weg über --bare besser, weil er die Dateien erstellt, ohne etwas auszuführen.

Ein Claude Code Plugin testen: ein nachvollziehbarer Verhaltensfall

Angenommen, das funktionierende Plugin enthält einen Skill namens release-notes. Sein Nutzen besteht nicht allein darin, Prosa zu schreiben. Er soll eine natürliche Anfrage zu einer Produktänderung erkennen und die dreiteilige Release-Note-Struktur des Teams liefern: Summary, Impact und Risk.

Die realistische Nutzeranfrage kommt in prompt.md. Danach folgt je ein deterministischer Grader für Ergebnis und Mechanismus. Deterministisch heißt: Die CLI prüft Trace oder Text direkt und ruft dafür kein Judge-Modell auf.

# evals/release-note/prompt.md
---
name: release-note
tags: [smoke]
runs: 3
max_turns: 8
timeout_seconds: 180
allowed_tools: [Skill]
---

Turn this change into a customer-facing release note: checkout now retries a failed payment once before showing an error.

# evals/release-note/graders/format.md
---
type: regex
target: last_message
pattern: 'Summary[\s\S]*Impact[\s\S]*Risk'
flags: i
---

# evals/release-note/graders/skill-fired.md
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?release-notes"'
---

release-notes wird durch den tatsächlichen name aus der SKILL.md des eigenen Skills ersetzt. Der Prompt nennt absichtlich weder den Skill noch die drei Überschriften. Damit prüft der Fall, ob das Plugin die Aufgabe erkennt und sein Format beisteuert. Gibt der Prompt bereits alle Antworten vor, kann die Variante ohne Plugin bestehen – und das Delta zeigt, dass das Plugin kaum zusätzlichen Nutzen brachte.

Der Frontmatter-Block entspricht dem aktuellen nativen Schema. In prompt.md bleiben Felder wie runs, max_turns, timeout_seconds, model, tags und allowed_tools auf der obersten Ebene. Werden Fixtures, Gesprächsverlauf oder Verzeichnisse benötigt, kommt case.yaml hinzu. Diese Datei erfordert schema_version: "1.1" und name; Ausführungsfelder wandern dort unter execution:.

Eval ausführen und Bericht richtig lesen

Vom Plugin-Stammverzeichnis aus startet claude plugin eval . den Test. Bei diesem einzelnen Fall erzeugt der Befehl drei Sitzungen mit Plugin und drei Baseline-Sitzungen. Fortschrittszeilen zeigen die Grader-Ergebnisse, sobald eine Sitzung endet. Die Zusammenfassung weist danach WITH, W/OUT, Δ, RUNS, COST und NOTES aus.

Sinnvoll ist diese Reihenfolge:

1. WITH beantwortet, ob die Sitzungen mit Plugin die Grader erfüllt haben.
2. W/OUT zeigt, wie oft Claude dasselbe Ergebnis allein erreicht hat.
3. Δ misst den Beitrag des Plugins. Ein positiver Wert ist nützlich. Liegt er nahe null, ist Ursachenanalyse nötig. Ein negativer Wert weist auf eine Regression hin.
4. COST ist eine Schätzung nach Listenpreisen und nicht zwingend der Betrag, der bei einem Abonnement berechnet wird.
5. NOTES verweist auf den Fehler mit der höchsten Gewichtung oder auf einen Ausführungsfehler in der Variante mit Plugin.

Jede Suite mit mindestens einem Fall schreibt aggregate-result.json und eine eigenständige report.html in ein mit Zeitstempel versehenes Ergebnisverzeichnis. Im HTML-Bericht lassen sich einzelne Durchläufe öffnen, Grader-Urteile samt Begründung prüfen und Prompt sowie Grader-Definitionen mit dem tatsächlichen Verhalten von Claude vergleichen. Das JSON enthält stabile CI-Felder, darunter Gesamtscore, bestandene Fälle, mittleres Delta, Teilstatus, Kostenschätzung, Dauer und Claude-Code-Version.

Vor dem Vertrauen in den Test eine Regression erzeugen

Nun muss der Test beweisen, dass er fehlschlagen kann. Dazu wird die Beschreibung des Skills release-notes vorübergehend durch eine vage Formulierung ersetzt, die die zu erkennende Aufgabe nicht mehr nennt. Der Eval-Fall bleibt unverändert. Anschließend denselben Befehl erneut ausführen, den neuen Bericht prüfen und die echte Beschreibung wiederherstellen.

Gesucht wird ein Verhaltensfehler: Der Skill-Grader besteht nicht mehr, das erwartete Format wird unzuverlässiger oder der Vorteil der Plugin-Variante schrumpft. Ein exakter Score lässt sich nicht vorhersagen, denn Agentendurchläufe variieren. Bleibt der Bericht trotz des absichtlichen Defekts bei den standardmäßigen drei Durchläufen praktisch unverändert, schützt der Fall das Plugin noch nicht. Dann sollte die Anfrage repräsentativer, der Ergebnis-Grader strenger oder ein negativer Fall ergänzt werden, bei dem der Skill nicht anspringen darf.

Diese absichtliche Störung entspricht der Prüftaste eines Rauchmelders. Ein grünes Dashboard ist wertlos, solange nicht feststeht, dass ein relevanter Defekt es rot werden lässt.

Vor weiteren Fällen das Budget für die Schleife festlegen

Schon ein Standardfall erzeugt sechs Agentensitzungen. Kommt ein LLM-Grader hinzu, entstehen für denselben Fall achtzehn Judge-Voten – drei für jede der sechs Sitzungen. Die Sitzungen selbst können mehrere Turns benötigen. Deshalb kann eine kleine Suite mehr Nutzung verbrauchen, als ihre Fallzahl vermuten lässt.

Drei Budgets gehören zu drei unterschiedlichen Entscheidungen:

Die Schleife mit einem Durchlauf ist absichtlich verrauscht. Sie eignet sich dazu, offensichtliche Fehler zu finden. Vor Annahme einer Änderung sollte anschließend mit den standardmäßigen drei Durchläufen bestätigt werden. Für häufige Prüfungen sind regex, tool_used, tool_order und file_exists vorzuziehen, weil sie keine zusätzlichen Judge-Aufrufe auslösen. Ein LLM-Grader lohnt sich für ein kurzes Ergebnis, dessen Qualität sich nicht als stabile Regel ausdrücken lässt.

Beim Kostenlimit ist eine Einschränkung wichtig. --max-cost-usd begrenzt die Listenpreisschätzung der CLI jeweils vor Beginn eines Durchlaufs. Bereits laufende Durchläufe enden regulär, daher kann die gemeldete Schätzung den Grenzwert überschreiten. Wird die Grenze erreicht, bleiben Teilergebnisse zurück und der Prozess endet mit Code 2. Das Flag ist ein Schutzgeländer, kein vorausbezahltes Guthaben.

Den Regressionstest an CI übergeben

Sobald die absichtliche Regression sichtbar ist und das wiederhergestellte Plugin besteht, wird genau diese Suite in die Versionsverwaltung übernommen. Das CI-Beispiel von Anthropic legt Agenten- und Judge-Modelle fest, schreibt results.json, verwendet einen Schwellenwert von 0.8, behält den Bericht lokal und setzt für die geschätzten Kosten ein Limit von $20. Außerdem übergibt es --trust-plugin. Das ist nur dann angemessen, wenn es sich bei dem ausgecheckten Plugin und der Suite um Code handelt, den man selbst ausführen würde.

Der vollständige Übergabebefehl lautet claude plugin eval . --trust-plugin --json results.json --threshold 0.8 --model claude-sonnet-5 --judge-model claude-haiku-4-5 --no-publish --max-cost-usd 20. Er gehört nach Installation und Authentifizierung von Claude Code in den Job; anschließend werden beide Ergebnisdateien archiviert.

Der Exit-Status des Befehls genügt als Build-Gate. Exit 0 bedeutet, dass jeder Fall geladen wurde und den Schwellenwert erreicht hat. Exit 1 deckt einen Score unterhalb des Schwellenwerts und mehrere Einrichtungsfehler ab. Exit 2 steht für einen Teildurchlauf, der durch das Kostenlimit oder eine anfängliche Ablehnung der Zugangsdaten verursacht wurde. results.json und report.html sollten auch bei einem Fehler archiviert werden. So bleibt sichtbar, ob das Plugin regressiert ist, der Durchlauf ein Timeout erreicht hat oder das Budget ihn gestoppt hat.

Festgelegte Modelle sind wichtig. Andernfalls kann ein Modell-Rollout wie eine Plugin-Regression aussehen. Dieselbe Disziplin gilt für den Reasoning-Aufwand: Qualität und Aufwand sollten getrennt getestet werden, damit sich eine Kostenänderung nicht in einem Verhaltensscore versteckt.

Sieben Plugin-Verhaltensweisen, die zuerst getestet werden sollten

Am meisten profitieren Teams, die Plugins für andere veröffentlichen. Bei einem privaten Helfer mag eine manuelle Prüfung genügen. Bei einem Marketplace- oder Organisations-Plugin erzeugt jede schwache Beschreibung, Tool-Freigabe oder Ausgabeänderung wiederkehrenden Supportaufwand.

Den Anfang sollten die ersten beiden Verhaltensweisen machen, deren Ausfall den Nutzern auffallen würde. Zehn vage Fälle sind weniger nützlich als ein Trigger-Test und ein Ergebnis-Test, die einen reproduzierbaren Defekt offenlegen.

Zwei Produkte, die sich auf nativen Plugin-Evals aufbauen lassen

1. Ein Delta-Gate für Pull Requests ist die stärkste Chance

Naheliegend ist ein schlankes CI-Produkt, das den nativen Befehl ausführt, aggregate-result.json liest und einen Review mit Score-Änderung, Delta, Kosten, fehlgeschlagenem Grader und Links zum archivierten Bericht veröffentlicht. Plugin-Teams und Marketplace-Betreiber zahlen für diese Entscheidungsebene, nicht für einen weiteren Evaluator.

Die Nachfrage ist noch jung, sendet aber ein klares kommerzielles Signal. claude code evals verzeichnet in den USA etwa 50 Suchanfragen pro Monat, 600% mehr als im Vorjahr, bei einem CPC von $17.61. Auch breitere Evaluierungsplattformen zeigen, dass Qualitätsbudgets existieren: Braintrust führt einen Pro-Tarif für $249 pro Monat. Das ist ein Anhaltspunkt für die Kategorie, keine Preisempfehlung für einen Plugin-Wrapper.

Die kleinste verkaufbare Version besteht aus einer GitHub Action und einem PR-Kommentar. Sie akzeptiert Plugin-Pfad, Schwellenwert, festgelegte Modelle und eine Obergrenze für geschätzte Kosten; lädt das native JSON und HTML hoch; und unterscheidet Exit 1 vom teilweisen Exit 2. Das Risiko liegt bei der Plattform: Anthropic könnte selbst PR-Berichte ergänzen. Dauerhaft differenzieren lässt sich das Produkt über repositoryübergreifende Richtlinien, historische Vergleiche und Freigaberegeln – nicht mit einer hübscheren Kopie des nativen Berichts.

2. Kuratierte Eval-Pakete für Skill-Autoren

Ein weiteres Produkt sind gepflegte Fallpakete für häufige Plugin-Aufgaben wie Code-Review, Changelog-Erstellung, Incident-Triage und sichere Tool-Auswahl. Ein Paket ist ein gewöhnliches evals/-Verzeichnis mit realistischen positiven und negativen Prompts sowie deterministischen Gradern. Teams können es anpassen, statt ihren Qualitätsmaßstab von Grund auf zu entwickeln.

Der direkte Suchbegriff claude code skill evals kommt in den USA auf etwa 10 Suchanfragen pro Monat. Das ist sehr wenig und macht daraus eher ein fokussiertes Zusatzprodukt als einen eigenständigen, Venture-finanzierten Markt. Das MVP ist ein hervorragendes Paket für eine wertvolle Plugin-Kategorie, versioniert nach Claude-Code-Releases und ergänzt um eine kurze Kalibrierungsanleitung. Die Einschränkung ist ebenso klar: claude plugin eval init schlägt bereits Fälle vor und testet sie. Pakete gewinnen nur, wenn ihre Domänenszenarien und Fehlerkriterien besser sind als generisch erzeugte Vorschläge.

Was der Befehl nicht löst

Native Evals beweisen nicht, dass ein Plugin universell gut ist. Sie zeigen, wie es sich mit den gewählten Prompts, Umgebungen, Modellen, Tool-Freigaben und Gradern verhalten hat. Schwache Prompts erzeugen schmeichelhafte Scores. Ein regulärer Ausdruck kann die richtige Überschrift bei falschem Inhalt belohnen. Ein LLM-Judge kann schwanken und fügt pro Grader und Durchlauf drei Voten hinzu.

Auch die Isolation ist eine ehrliche Einschränkung. Jeder Durchlauf startet sauber, sodass Projektdateien, Nutzereinstellungen, Hooks und persönliche Server fehlen. Das ist hervorragend für Reproduzierbarkeit und problematisch für einen Fall, der seine Fixtures nicht deklariert hat. Tools jenseits der schreibgeschützten Auswahl benötigen eine ausdrückliche Freigabe auf der Kommandozeile. Echte MCP-Server eines Plugins verlangen zusätzliches Opt-in und Berechtigungen. Hooks und reale Server gehören in eine isolierte Runner-Umgebung, weil sie außerhalb der Agenten-Sandbox agieren können.

Schließlich sollten max_turns und timeout_seconds nicht so weit reduziert werden, dass legitime Arbeit an die Grenze stößt. Ein Durchlauf, der ein Timeout oder sein Turn-Limit erreicht, wird als Fehler erfasst und senkt meist den Score. Für die beabsichtigte Aufgabe muss genug Spielraum bleiben; die Suite als Ganzes wird stattdessen über die geschätzte Kostengrenze kontrolliert.

Am Montag sollte ein Plugin-Betreiber einen Trigger-Fall ergänzen, ihn absichtlich zum Scheitern bringen, das Plugin wiederherstellen und genau diesen Check mit einem CI-Limit versehen. Wenn dieses Release-System über alle Plugins eines Teams hinweg aufgebaut werden soll, unterstütze ich gern bei der Konzeption des produktiven Gates.