Claude-skillen som reviewer sin egen OpenAPI-spec

Be Claude designe et API, og du får noe som ser riktig ut: flertallsnavn, en pagineringsparameter, et versjonsprefiks. Så leser du nøyere, og ett endepunkt bruker page_size der alle andre lister bruker limit, en valideringsfeil er dokumentert som en 500, og spec-en leveres med en nullable: true som ikke finnes i OpenAPI 3.1. Hver feil er liten. Sammen er de forskjellen mellom et API som virker og et API som forblir konsistent under endring — og ingenting i en «her er prinsippene»-prompt tvinger frem det andre.

Resultatet er api-discipline, og poenget er ikke at den kan REST-konvensjoner — det kan hver skill i denne nisjen. Poenget er at den sjekker sitt eget resultat før den leverer tilbake: validator-ren OpenAPI 3.1, en obligatorisk konsistenssjekk på tvers av endepunkter, og en brytende-endring-diff på hver redigering. Den er gratis og MIT-lisensiert: github.com/Skillproofdev/api-discipline.

Gapet: alle underviser i prinsippene, ingen håndhever dem

Før vi skrev en eneste linje kartla vi 84 API-design- og OpenAPI-skills på tvers av vår indeks på 16 682 skills, pluss det frittstående web-økosystemet. Mønsteret er konsekvent. Det største repoet (37 600 stjerner) er en begrepslærebok med null håndheving. Det best konstruerte (10 500 stjerner) navngir en linter og stopper der.

Og det betyr noe for hva vi ærlig kunne påstå. Validator-rent resultat alene er allerede et løst, konkurransetungt felt — 10 500-stjerners-skillen får deg dit. Å levere «vi kjører også en linter» ville vært støy. Så vi lette etter det ingen håndhever, og fant fire ting som fantes i ingen av de 84:

1. En konsistenssjekk på tvers av endepunkter som en obligatorisk fase. Ti definerte sjekker — store/små bokstaver, flertallsform, ett delt feilskjema, identiske pagineringsparametre, ensartede id-/tidsstempelformater, operationId-mønster, samme-handling-samme-statuskode — kjøres på tvers av hvert endepunkt før levering. Hver konkurrent har, i beste fall, ett «vær konsistent»-kulepunkt.
2. Brytende-endring-disiplin som utløses ved redigeringer. Hver spec-redigering får en oppramset brytende-endring-sjekk, mekanisk støttet av oasdiff breaking når tilgjengelig. Verktøyet er modent; ingen kartlagt skill kobler det inn.
3. HTTP-semantikk som regler, ikke trivia. PUT erstatter, PATCH gjør delvise endringer, POST oppretter med 201 + Location, DELETE returnerer 204 — håndhevet med en statuskode-tabell, ikke listet som «begreper å kunne».
4. En review-/utvid-utdata-kontrakt. «Review denne spec-en» returnerer funn koblet til sjekklisten med plasseringer og fikser; «legg til et endepunkt» returnerer en diff som arver den eksisterende spec-ens konvensjoner pluss en brytende-endringer-blokk. Konkurrenter definerer bare grønn-eng-utdata.

Det er den ubestridte grunnen: ikke validering, men sjekken som kjører etter validering, pluss en publisert benchmark som støtter det.

Benchmarken: målt, med tapene liggende igjen

Sju oppgaver — to grønn-eng-design, to spec-utvidelser, to reviewer av mangelfulle spec-er med 22 plantede brudd mellom dem, ett spørsmål om konvensjoner. Hver kjørte to ganger: én Claude Sonnet-agent bar, én som leser SKILL.md først, identiske prompter. Spec-er ble scoret mekanisk med redocly lint og spectral lint, redigeringer diffet med oasdiff breaking, og plantede brudd-fangster dømt av uavhengige verifiseringsagenter.

Metrikk (lavere er bedre)	base	skill
Validatorfeil, grønn eng (redocly)	18	0
Konsistensbrudd, alle 4 designoppgaver	6	0
HTTP-semantikkfeil, alle 4 designoppgaver	3	0
Plantede brudd fanget, T6-review (høyere bedre)	10/10	9/10

Målt 2026-07-10 med Redocly CLI 2.38.0, Spectral 6.16.1 og oasdiff 1.23.0. Full detalj per funn finner du i bench/results/verdict.md.

Validator-gapet er én ren historie: begge bare-kjøringer sendte OpenAPI 3.0 nullable: true inn i dokumenter deklarert openapi: 3.1.0 — en strukturell feil i 3.1, som bruker type: [x, 'null']. Tolv forekomster i den første grønn-eng-oppgaven, seks i den andre. Skill-kjøringen brukte 3.1-formen gjennomgående og validerte rent. Konsistens- og semantikk-seirene har samme form: bare-kjøringene sendte verb-i-sti-endepunkter (/tasks/{id}/complete), et andre ad hoc-feilskjema ved siden av det delte, og en opprettelse som returnerte 200 i stedet for 201. Skill-kjøringen modellerte handlinger som substantiv-underressurser og gjenbrukte ett feilskjema overalt — 0 på tvers av alle fire designoppgaver.

Der skillen tapte — og ett resultat vi ikke tar æren for

To ærlige notiser, fordi metodikken vår krever at tapene vises ved siden av seirene.

Skillen tapte T6 med ett plantet brudd. På den semantikk-tunge reviewen gikk bare-agentens frie gjennomgang eksaustivt gjennom hver operasjon og fanget en 201 Created på POST /articles uten Location-header. Skill-agentens review, organisert rundt konsistenssjekklisten, flagget alle fire HTTP-metode-defekter og alle fem konsistens-brudd, men skannet ikke hver 201 for sin Location — 9/10 mot 10/10. Strukturert review dekket mindre enn en eksaustiv lesning fanget. Det er nå fikset i sjekklisten med en eksplisitt «hver 201 har Location»-linje.

Ett brytende-endring-resultat er utelatt fra hovedtallene. På spec-utvidelsesoppgaven rapporterte skill-agenten at den hadde sett et fasit-hint lekke inn i oppgavefilen («begge endringene er brytende») før den analyserte — en protokollglipp, siden skill-armen skal bare lese SKILL.md. Så det resultatet er ikke hevdet som en uavhengig seier, selv om det ser bra ut på papiret. To ting gjør det underliggende funnet robust likevel: bare-armen, som aldri leser oppgavefilen, konkluderte uavhengig at begge endringene var brytende; og oasdiff bekreftet mekanisk brytende-flaten uansett hva noen av agentene trodde. Hovedpåstandene hviler på validering, konsistens og semantikk — ingen av dem berøres av lekkasjen.

Installasjon

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

Start Claude Code på nytt. Den trigger på «design et API», «legg til/utvid et endepunkt», «review denne OpenAPI-spec-en», og spørsmål om REST-konvensjoner — og holder seg unna rent GraphQL-arbeid, klient-SDK-kodegenerering og API-sikkerhetstesting. Den inngår sammen med token-discipline, som kutter hva flertrinnsarbeid koster, og research-discipline, som kutter hva research bommer på — denne kutter hva API-kontraktene dine driver inn i.

Ofte stilte spørsmål

En skill med 10 500 stjerner produserer allerede gyldig OpenAPI. Hvorfor denne? Fordi gyldig ikke er det samme som konsistent. En linter fanger en ødelagt $ref; den fanger ikke at ett endepunkt paginerer med page_size mens resten bruker limit, eller en opprettelse som returnerer 200. Den konsistenssjekken på tvers av endepunkter er den ubestridte grunnen — det er det de populære skillene ikke håndhever, og det er der bare-kjøringene samlet 6 brudd mot skillens 0.

Håndterer den redigeringer av en eksisterende spec, ikke bare grønn eng? Ja, og den behandler dem annerledes. Nye endepunkter lagt til en eksisterende spec arver dens konvensjoner selv når de strider mot skillens standarder — konsistens med kontrakten andre er avhengige av, slår skillens preferanser. Hver redigering får også en oppramset brytende-endring-sjekk, støttet av oasdiff breaking når verktøyet er tilgjengelig.

Trenger den oasdiff eller en validator installert for å virke? Nei. Når redocly/spectral eller oasdiff kan kjøre, bruker den dem og rapporterer kommandoen og resultatet. Når de ikke kan, sier den det eksplisitt og kjører en definert selvsjekk-reserveløsning — alle $ref-er løst opp, unike operationId-er, hver stiparameter deklarert, hvert svar har en beskrivelse. Den hopper aldri stille over sjekken.

Er benchmarken reproduserbar? Ja. Sju oppgaver, to armer, mekanisk scoring der det er mulig, og den forhåndsregistrerte fasiten er sjekket inn i repoet under bench/ground-truth/. Hele metoden, detaljer per funn, og T6-tapet og T4-integritetsnotisen er alle i bench/results/verdict.md — ingenting er skjult.