Das Claude-Skill, das seine eigene OpenAPI-Spec prüft

Bittet man Claude, eine API zu entwerfen, sieht das Ergebnis erstmal richtig aus: Plural-Substantive, ein Pagination-Parameter, ein Versionspräfix. Dann liest man genauer, und ein Endpoint benutzt page_size, wo alle anderen Listen limit nutzen, ein Validierungsfehler ist als 500 dokumentiert, und die Spec liefert ein nullable: true, das es in OpenAPI 3.1 gar nicht mehr gibt. Jeder Fehler für sich ist klein. Zusammen sind sie der Unterschied zwischen einer API, die funktioniert, und einer, die unter Änderungen konsistent bleibt – und nichts in einem „hier sind die Prinzipien“-Prompt erzwingt das Zweite.

Das Ergebnis heißt api-discipline, und der Punkt ist nicht, dass es REST-Konventionen kennt – das kann jedes Skill in dieser Nische. Der Punkt ist, dass es die eigene Ausgabe prüft, bevor es sie zurückgibt: validator-sauberes OpenAPI 3.1, ein verpflichtender endpointübergreifender Konsistenz-Check und ein Breaking-Change-Diff bei jeder Bearbeitung. Kostenlos und MIT-lizenziert: github.com/Skillproofdev/api-discipline.

Die Lücke: alle lehren die Prinzipien, niemand setzt sie durch

Bevor wir eine Zeile geschrieben haben, haben wir 84 API-Design- und OpenAPI-Skills in unserem 16.682-Skills-Index plus das eigenständige Web-Ökosystem gesichtet. Das Muster ist durchgängig. Das größte Repo (37,6k Stars) ist ein Konzepte-Lehrbuch ohne jede Durchsetzung. Das am besten durchdachte (10,5k Stars) nennt einen Linter und hört dann auf.

Und das war wichtig für das, was wir ehrlich behaupten konnten. Validator-sauberer Output allein ist bereits ein gelöster, umkämpfter Bereich – das 10,5k-Stars-Skill liefert das schon. Zu behaupten „wir lassen auch einen Linter laufen“ wäre Rauschen gewesen. Also haben wir gesucht, was niemand durchsetzt, und vier Dinge gefunden, die in keinem der 84 vorkamen:

1. Ein endpointübergreifender Konsistenz-Audit als Pflichtdurchgang. Zehn definierte Checks – Schreibweise, Pluralisierung, ein gemeinsames Fehlerschema, identische Pagination-Parameter, einheitliche id-/Timestamp-Formate, operationId-Muster, gleiche Aktion gleicher Statuscode – laufen vor der Auslieferung über jeden Endpoint. Jeder Konkurrent hat höchstens einen „sei konsistent“-Punkt.
2. Breaking-Change-Disziplin, die bei jeder Bearbeitung greift. Jede Spec-Bearbeitung bekommt einen aufgelisteten Breaking-Change-Durchgang, mechanisch gestützt durch oasdiff breaking, wo verfügbar. Das Tooling ist ausgereift; kein gesichtetes Skill bindet es ein.
3. HTTP-Semantik als Regeln, nicht als Trivia. PUT ersetzt, PATCH ändert teilweise, POST erstellt mit 201 + Location, DELETE liefert 204 – durchgesetzt mit einer Statuscode-Tabelle, nicht als „Konzepte zum Wissen“ aufgelistet.
4. Ein Output-Vertrag für Review und Erweiterung. „Review this spec“ liefert Funde, die an der Checkliste hängen, mit Fundort und Fix; „add an endpoint“ liefert einen Diff, der die Konventionen der bestehenden Spec übernimmt, plus einen Breaking-Changes-Block. Konkurrenten definieren nur Greenfield-Output.

Das ist der unumstrittene Boden: nicht die Validierung, sondern der Audit, der nach der Validierung läuft, plus ein veröffentlichter Benchmark als Beleg.

Der Benchmark: gemessen, mit den Verlusten drin

Sieben Aufgaben – zwei Greenfield-Designs, zwei Spec-Erweiterungen, zwei Reviews fehlerhafter Specs mit 22 platzierten Verstößen zusammen, eine Konventionsfrage. Jede lief zweimal: ein Claude-Sonnet-Agent nackt, einer mit vorher gelesener SKILL.md, identische Prompts. Specs wurden mechanisch mit redocly lint und spectral lint bewertet, Bearbeitungen mit oasdiff breaking verglichen, und die Treffer bei platzierten Verstößen von unabhängigen Verifizierungs-Agenten beurteilt.

Metrik (niedriger ist besser)	Base	Skill
Validator-Fehler, Greenfield (redocly)	18	0
Konsistenzverstöße, alle 4 Design-Aufgaben	6	0
HTTP-Semantik-Fehler, alle 4 Design-Aufgaben	3	0
Platzierte Verstöße gefunden, T6-Review (höher ist besser)	10/10	9/10

Gemessen am 10.07.2026 mit Redocly CLI 2.38.0, Spectral 6.16.1 und oasdiff 1.23.0. Vollständige Details pro Fund stehen in bench/results/verdict.md.

Die Validator-Lücke ist eine saubere Geschichte: Beide nackten Läufe schrieben OpenAPI-3.0-nullable: true in Dokumente, die als openapi: 3.1.0 deklariert waren – ein struktureller Fehler in 3.1, das type: [x, 'null'] verwendet. Zwölf Vorkommen in der ersten Greenfield-Aufgabe, sechs in der zweiten. Der Skill-Lauf nutzte durchgängig die 3.1-Form und validierte sauber. Die Konsistenz- und Semantik-Siege haben dieselbe Form: Die nackten Läufe lieferten Verb-im-Pfad-Endpoints (/tasks/{id}/complete), ein zweites Ad-hoc-Fehlerschema neben dem gemeinsamen und ein Create, das 200 statt 201 zurückgab. Der Skill-Lauf modellierte Aktionen als Substantiv-Unterressourcen und nutzte durchgängig ein Fehlerschema – 0 über alle vier Design-Aufgaben.

Wo das Skill verloren hat – und ein Ergebnis, das wir uns nicht anrechnen

Zwei ehrliche Anmerkungen, denn unsere Methodik verlangt die Verluste neben den Gewinnen.

Das Skill hat T6 um einen platzierten Verstoß verloren. Bei der semantiklastigen Review fand der nackte Agent mit seinem freien Durchgang jede Operation und entdeckte ein 201 Created bei POST /articles ohne Location-Header. Die Review des Skill-Agenten, organisiert um die Konsistenz-Checkliste, markierte alle vier HTTP-Methoden-Fehler und alle fünf Konsistenz-Seeds, prüfte aber nicht jedes 201 auf seinen Location-Header – 9/10 gegen 10/10. Strukturierte Review deckte weniger ab als ein erschöpfendes Lesen. Das ist jetzt in der Checkliste mit einer expliziten „jedes 201 braucht Location“-Zeile behoben.

Ein Breaking-Change-Ergebnis ist aus der Schlagzeile ausgeschlossen. Bei der Spec-Erweiterungsaufgabe meldete der Skill-Agent, er habe einen Ground-Truth-Hinweis gesehen, der in die Aufgabendatei durchgesickert war („both changes are breaking“), bevor er analysiert hat – ein Protokollfehler, denn der Skill-Arm sollte nur die SKILL.md lesen. Dieses Ergebnis wird also nicht als unabhängiger Sieg beansprucht, auch wenn es auf dem Papier gut aussieht. Zwei Dinge machen den zugrunde liegenden Befund trotzdem robust: Der nackte Arm, der die Aufgabendatei nie liest, kam unabhängig zu demselben Schluss, dass beide Änderungen breaking sind; und oasdiff bestätigte die Breaking-Fläche mechanisch, unabhängig davon, was einer der beiden Agenten glaubte. Die Schlagzeilenbehauptungen beruhen auf Validierung, Konsistenz und Semantik – keine davon berührt das Leck.

Installation

git clone https://github.com/Skillproofdev/api-discipline ~/.claude/skills/api-discipline

Claude Code neu starten. Es greift bei „design an API“, „add/extend an endpoint“, „review this OpenAPI spec“ und REST-Konventionsfragen – und hält sich raus bei reinen GraphQL-Arbeiten, Client-SDK-Codegen und API-Sicherheitstests. Es reiht sich neben token-discipline, das senkt, was mehrstufige Arbeit kostet, und research-discipline, das senkt, was Recherche falsch macht – dieses hier senkt, wohin deine API-Verträge abdriften.

FAQ

Ein 10,5k-Stars-Skill liefert doch schon gültiges OpenAPI. Wozu dieses? Weil gültig nicht dasselbe ist wie konsistent. Ein Linter erkennt eine kaputte $ref; er erkennt nicht, dass ein Endpoint mit page_size paginiert, während der Rest limit nutzt, oder dass ein Create 200 statt 201 zurückgibt. Dieser endpointübergreifende Konsistenz-Audit ist der unumstrittene Boden – genau das, was die populären Skills nicht durchsetzen, und dort, wo die nackten Läufe 6 Verstöße gegen 0 beim Skill anhäuften.

Kann es auch bestehende Specs bearbeiten, nicht nur Greenfield-Design? Ja, und es behandelt sie anders. Neue Endpoints, die zu einer bestehenden Spec hinzugefügt werden, übernehmen deren Konventionen, auch wenn sie den Standardwerten des Skills widersprechen – Konsistenz mit dem Vertrag, auf den sich andere verlassen, schlägt die Vorlieben des Skills. Jede Bearbeitung bekommt zusätzlich einen aufgelisteten Breaking-Change-Durchgang, gestützt durch oasdiff breaking, wenn das Tool verfügbar ist.

Braucht es oasdiff oder einen Validator installiert, um zu funktionieren? Nein. Wenn redocly/spectral oder oasdiff laufen können, nutzt es sie und meldet Befehl und Ergebnis. Wenn nicht, sagt es das ausdrücklich und führt einen definierten Selbstcheck als Fallback aus – alle $refs aufgelöst, eindeutige operationIds, jeder Pfadparameter deklariert, jede Response mit Beschreibung. Es überspringt einen Check nie stillschweigend.

Ist der Benchmark reproduzierbar? Ja. Sieben Aufgaben, zwei Arme, wo möglich mechanische Bewertung, und die vorregistrierte Ground Truth liegt im Repo unter bench/ground-truth/. Die vollständige Methode, Details pro Fund sowie der T6-Verlust und die Integritätsfußnote zu T4 stehen alle in bench/results/verdict.md – nichts wird verschwiegen.