Claude-skillen som granskar sin egen OpenAPI-spec

Be Claude designa ett API och du får något som ser rätt ut: substantiv i plural, en pagineringsparameter, ett versionsprefix. Sedan läser du noggrannare och en endpoint använder page_size där alla andra listor använder limit, ett valideringsfel dokumenteras som en 500, och specifikationen levereras med en nullable: true som inte finns i OpenAPI 3.1. Varje misstag är litet. Tillsammans är de skillnaden mellan ett API som fungerar och ett som förblir konsekvent när det ändras — och inget i en "här är principerna"-prompt tvingar fram det andra.

Resultatet är api-discipline, och poängen är inte att den kan REST-konventioner — det gör alla skills i den här nischen. Poängen är att den kontrollerar sin egen utdata innan den lämnar tillbaka den: validatorren OpenAPI 3.1, en obligatorisk konsekvenskontroll mellan endpoints och en diff för breaking changes vid varje redigering. Den är gratis och MIT-licensierad: github.com/Skillproofdev/api-discipline.

Luckan: alla lär ut principerna, ingen tvingar fram dem

Innan vi skrev en enda rad kartlade vi 84 API-design- och OpenAPI-skills i vårt index på 16 682 skills plus det fristående webbekosystemet. Mönstret är konsekvent. Det största repot (37 600 stjärnor) är en läroboksgenomgång av begrepp utan enforcement. Det bäst konstruerade (10 500 stjärnor) namnger en linter och stannar där.

Och det spelar roll för vad vi ärligt kunde påstå. Validatorren utdata i sig är redan ett löst, konkurrensutsatt fält — skillen med 10 500 stjärnor tar dig dit. Att leverera "vi kör en linter också" hade varit brus. Så vi letade efter det ingen tvingar fram, och hittade fyra saker som fanns i ingen av de 84:

1. En konsekvensrevision mellan endpoints som en obligatorisk kontroll. Tio definierade kontroller — skrivsätt, plural, ett delat felschema, identiska pagineringsparametrar, enhetliga id-/tidsstämpelformat, operationId-mönster, samma-handling-samma-statuskod — körs över varje endpoint innan leverans. Varje konkurrent har som mest en punkt om "var konsekvent."
2. Disciplin kring breaking changes som triggas vid redigeringar. Varje redigering av specifikationen får en uppräknad genomgång av breaking changes, mekaniskt backad av oasdiff breaking när det finns tillgängligt. Verktyget är moget; ingen kartlagd skill kopplar in det.
3. HTTP-semantik som regler, inte trivia. PUT ersätter, PATCH gör delvisa ändringar, POST skapar med 201 + Location, DELETE returnerar 204 — tvingat fram med en statuskodstabell, inte listat som "begrepp att kunna."
4. Ett kontrakt för utdata vid granskning/utökning. "Granska den här specifikationen" ger fynd kopplade till checklistan med platser och fixar; "lägg till en endpoint" ger en diff som ärver den befintliga specifikationens konventioner plus ett block med breaking changes. Konkurrenterna definierar bara utdata för greenfield-design.

Det är den obestridda marken: inte validering, utan revisionen som körs efter valideringen, plus ett publicerat benchmark som backar upp det.

Benchmarket: uppmätt, med förlusterna kvar

Sju uppgifter — två greenfield-designer, två utökningar av specifikationer, två granskningar av bristfälliga specifikationer med 22 planterade brott mellan dem, en fråga om konventioner. Varje kördes två gånger: en Claude Sonnet-agent utan skill, en som läste SKILL.md först, identiska prompter. Specifikationer poängsattes mekaniskt med redocly lint och spectral lint, redigeringar diffades med oasdiff breaking, och fångade planterade brott bedömdes av oberoende verifieringsagenter.

Mått (lägre är bättre)	bas	skill
Validatorfel, greenfield (redocly)	18	0
Konsekvensbrott, alla 4 designuppgifter	6	0
HTTP-semantikfel, alla 4 designuppgifter	3	0
Fångade planterade brott, T6-granskning (högre bättre)	10/10	9/10

Uppmätt 2026-07-10 med Redocly CLI 2.38.0, Spectral 6.16.1 och oasdiff 1.23.0. Fullständiga fynddetaljer finns i bench/results/verdict.md.

Validatorgapet är en tydlig historia: båda körningarna utan skill skickade OpenAPI 3.0-formen nullable: true in i dokument deklarerade som openapi: 3.1.0 — ett strukturellt fel i 3.1, som använder type: [x, 'null']. Tolv förekomster i den första greenfield-uppgiften, sex i den andra. Skillkörningen använde 3.1-formen genomgående och validerade rent. Konsekvens- och semantikvinsterna följer samma mönster: körningarna utan skill levererade endpoints med verb i sökvägen (/tasks/{id}/complete), ett andra ad hoc-felschema vid sidan av det delade, och en skapa-endpoint som returnerade 200 istället för 201. Skillkörningen modellerade handlingar som substantiv-delresurser och återanvände ett felschema överallt — 0 över alla fyra designuppgifter.

Där skillen förlorade — och ett resultat vi inte tar åt oss äran för

Två ärliga anmärkningar, för vår metodik kräver att förlusterna redovisas bredvid vinsterna.

Skillen förlorade T6 med ett enda planterat brott. På den semantiktunga granskningen gick den fria genomgången utan skill igenom varje operation uttömmande och fångade en 201 Created på POST /articles utan Location-header. Skillagentens granskning, organiserad kring konsekvenschecklistan, flaggade alla fyra HTTP-metodfel och alla fem konsekvensfrön men skannade inte varje 201 efter sin Location — 9/10 mot 10/10. Strukturerad granskning täckte mindre än en uttömmande läsning. Det är nu fixat i checklistan med en uttrycklig rad: "varje 201 har Location."

Ett resultat om breaking changes är exkluderat från huvudsiffran. På uppgiften om att utöka specifikationen rapporterade skillagenten att den sett en ledtråd om facit läcka in i uppgiftsfilen ("båda ändringarna är breaking") innan analysen — ett protokollfel, eftersom skillgrenen bara ska läsa SKILL.md. Så det resultatet påstås inte vara en oberoende vinst, även om det ser bra ut på pappret. Två saker gör det underliggande fyndet robust ändå: grenen utan skill, som aldrig läser uppgiftsfilen, kom oberoende fram till att båda ändringarna var breaking; och oasdiff bekräftade mekaniskt breaking-ytan oavsett vad någon av agenterna trodde. Huvudpåståendena vilar på validering, konsekvens och semantik — inget av det läckan rör.

Installation

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

Starta om Claude Code. Den triggas av "designa ett API," "lägg till/utöka en endpoint," "granska den här OpenAPI-specifikationen" och frågor om REST-konventioner — och håller sig undan från rent GraphQL-arbete, kodgenerering för klient-SDK:er och API-säkerhetstestning. Den ansluter till token-discipline, som minskar vad flerstegsarbete kostar, och research-discipline, som minskar vad research har fel om — den här minskar vad dina API-kontrakt glider mot.

FAQ

En skill med 10 500 stjärnor ger redan giltig OpenAPI. Varför den här? För att giltig inte är samma sak som konsekvent. En linter fångar en trasig $ref; den fångar inte att en endpoint paginerar med page_size medan resten använder limit, eller att en skapa-endpoint returnerar 200. Den konsekvensrevisionen mellan endpoints är den obestridda marken — det är vad de populära skillsen inte tvingar fram, och det är där körningarna utan skill drog på sig 6 brott mot skillens 0.

Hanterar den redigeringar av en befintlig specifikation, inte bara greenfield-design? Ja, och den behandlar dem annorlunda. Nya endpoints som läggs till en befintlig specifikation ärver dess konventioner även när de krockar med skillens standarder — konsekvens med kontraktet andra människor förlitar sig på väger tyngre än skillens preferenser. Varje redigering får också en uppräknad genomgång av breaking changes, backad av oasdiff breaking när verktyget finns tillgängligt.

Behöver den oasdiff eller en validator installerad för att fungera? Nej. När redocly/spectral eller oasdiff kan köras använder den dem och rapporterar kommandot och resultatet. När de inte kan säger den det uttryckligen och kör en definierad fallback för självkontroll — alla $ref upplöses, unika operationId, varje sökvägsparameter deklarerad, varje svar har en beskrivning. Den hoppar aldrig tyst över kontrollen.

Är benchmarket reproducerbart? Ja. Sju uppgifter, två grenar, mekanisk poängsättning där det går, och det förregistrerade facit finns incheckat i repot under bench/ground-truth/. Hela metoden, fynddetaljerna och T6-förlusten samt fotnoten om T4:s integritet finns alla i bench/results/verdict.md — inget döljs.