Claude-skillen der reviderer sin egen OpenAPI-spec

Bed Claude om at designe en API, og du får noget, der ser rigtigt ud: flertalsnavneord, en pagineringsparameter, et versionspræfiks. Så læser du nøje efter, og ét endpoint bruger page_size, hvor alle andre lister bruger limit, en valideringsfejl er dokumenteret som en 500, og specen leveres med en nullable: true, der ikke findes i OpenAPI 3.1. Hver fejl er lille. Tilsammen er de forskellen mellem en API, der virker, og en API, der forbliver konsistent under forandring — og intet i en "her er principperne"-prompt tvinger den anden frem.

Resultatet er api-discipline, og pointen er ikke, at den kender REST-konventioner — det gør hver eneste skill i denne niche. Pointen er, at den tjekker sit eget output, før den afleverer: validator-ren OpenAPI 3.1, et obligatorisk konsistenstjek på tværs af endpoints og en breaking-change-diff på hver eneste redigering. Den er gratis og MIT-licenseret: github.com/Skillproofdev/api-discipline.

Hullet: alle underviser i principperne, ingen håndhæver dem

Før vi skrev en eneste linje, gennemgik vi 84 API-design- og OpenAPI-skills på tværs af vores indeks på 16,682 skills plus det selvstændige web-økosystem. Mønstret er konsistent. Det største repo (37.6k stjerner) er en begrebslærebog med nul håndhævelse. Det bedst konstruerede (10.5k stjerner) navngiver en linter og stopper der.

Og det havde betydning for, hvad vi ærligt kunne påstå. Validator-rent output alene er allerede et løst, konkurrencepræget rum — 10.5k-stjerne-skillen bringer dig derhen. At skibe "vi kører også en linter" ville have været støj. Så vi ledte efter det, ingen håndhæver, og fandt fire ting, der fandtes i ingen af de 84:

1. Et konsistenstjek på tværs af endpoints som et obligatorisk trin. Ti definerede tjek — casing, flertalsdannelse, ét delt fejlskema, identiske pagineringsparametre, ensartede id-/tidsstempelformater, operationId-mønster, samme-handling-samme-statuskode — kørt på tværs af hvert endpoint før levering. Enhver konkurrent har højst ét "vær konsistent"-punkt.
2. Breaking-change-disciplin, der udløses ved redigeringer. Hver spec-redigering får et opremset breaking-change-tjek, mekanisk understøttet af oasdiff breaking, når tilgængelig. Værktøjet er modent; ingen gennemgået skill kobler det på.
3. HTTP-semantik som regler, ikke trivia. PUT erstatter, PATCH er delvist, POST opretter med 201 + Location, DELETE returnerer 204 — håndhævet med en statuskodetabel, ikke listet som "begreber at kende."
4. En review/udvid-output-kontrakt. "Review this spec" returnerer fund knyttet til tjeklisten med placeringer og rettelser; "add an endpoint" returnerer en diff, der arver den eksisterende specs konventioner plus en breaking-changes-blok. Konkurrenter definerer kun greenfield-output.

Det er den ubestridte grund: ikke validering, men tjekket, der kører efter validering, plus en offentliggjort benchmark til at bakke det op.

Benchmarken: målt, med tabene efterladt

Syv opgaver — to greenfield-designs, to spec-udvidelser, to reviews af fejlbehæftede specs med 22 plantede overtrædelser imellem sig, ét spørgsmål om konventioner. Hver kørte to gange: én Claude Sonnet-agent bar, én der læste SKILL.md først, identiske prompts. Specs blev scoret mekanisk med redocly lint og spectral lint, redigeringer diffet med oasdiff breaking, og plantede overtrædelser fanget bedømt af uafhængige verifikationsagenter.

Metrik (lavere er bedre)	base	skill
Validatorfejl, greenfield (redocly)	18	0
Konsistensbrud, alle 4 designopgaver	6	0
HTTP-semantikfejl, alle 4 designopgaver	3	0
Plantede overtrædelser fanget, T6-review (højere 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. Fulde detaljer per fund er i bench/results/verdict.md.

Validatorgabet er én ren historie: begge bar-kørsler udsendte OpenAPI 3.0 nullable: true i dokumenter erklæret openapi: 3.1.0 — en strukturel fejl i 3.1, som bruger type: [x, 'null']. Tolv forekomster i den første greenfield-opgave, seks i den anden. Skill-kørslen brugte 3.1-formen konsekvent og validerede rent. Konsistens- og semantikgevinsterne har samme form: bar-kørslerne leverede verb-i-sti-endpoints (/tasks/{id}/complete), et andet ad hoc-fejlskema ved siden af det delte, og en create, der returnerede 200 i stedet for 201. Skill-kørslen modellerede handlinger som navneord-underressourcer og genbrugte ét fejlskema overalt — 0 på tværs af alle fire designopgaver.

Hvor skillen tabte — og ét resultat vi ikke tager æren for

To ærlige bemærkninger, for vores metode kræver, at tabene står ved siden af sejrene.

Skillen tabte T6 med én plantet overtrædelse. På den semantiktunge review gik bar-agentens frie gennemløb udtømmende igennem hver operation og fangede en 201 Created på POST /articles uden Location-header. Skill-agentens review, organiseret omkring konsistenstjeklisten, flagede alle fire HTTP-metode-defekter og alle fem konsistensplantninger, men scannede ikke hver 201 for sin Location — 9/10 mod 10/10. Struktureret review underdækkede, hvad et udtømmende gennemløb fangede. Det er nu rettet i tjeklisten med en eksplicit "hver 201 har en Location"-linje.

Ét breaking-change-resultat er udelukket fra overskriften. På spec-udvidelsesopgaven rapporterede skill-agenten, at den havde set et grundsandhedshint lækket ind i opgavefilen ("both changes are breaking"), før den analyserede — et protokolglip, siden skill-armen kun burde læse SKILL.md. Så det resultat gøres ikke krav på som en uafhængig sejr, selv om det ser godt ud på papiret. To ting gør det underliggende fund robust alligevel: bar-armen, der aldrig læser opgavefilen, konkluderede uafhængigt, at begge ændringer var breaking; og oasdiff bekræftede mekanisk breaking-overfladen uanset, hvad nogen af agenterne troede. Overskriftspåstandene hviler på validering, konsistens og semantik — ingen af dem, lækagen rører.

Installation

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

Genstart Claude Code. Den udløses af "design an API," "add/extend an endpoint," "review this OpenAPI spec" og REST-konventionsspørgsmål — og holder sig væk fra rent GraphQL-arbejde, client-SDK-kodegenerering og API-sikkerhedstestning. Den slutter sig til token-discipline, som skærer i, hvad flertrinsarbejde koster, og research-discipline, som skærer i, hvad research tager fejl om — den her skærer i, hvad dine API-kontrakter driver ind i.

FAQ

En 10.5k-stjerne-skill producerer allerede gyldig OpenAPI. Hvorfor den her? Fordi gyldig ikke er det samme som konsistent. En linter fanger en ødelagt $ref; den fanger ikke ét endpoint, der paginerer med page_size, mens resten bruger limit, eller en create, der returnerer 200. Det konsistenstjek på tværs af endpoints er den ubestridte grund — det er, hvad de populære skills ikke håndhæver, og det er, hvor bar-kørslerne samlede 6 overtrædelser mod skillens 0.

Håndterer den redigeringer af en eksisterende spec, ikke kun greenfield-design? Ja, og den behandler dem forskelligt. Nye endpoints tilføjet til en eksisterende spec arver dens konventioner, selv når de strider mod skillens standarder — konsistens med kontrakten, andre mennesker afhænger af, slår skillens præferencer. Hver redigering får også et opremset breaking-change-tjek, understøttet af oasdiff breaking, når værktøjet er tilgængeligt.

Kræver den oasdiff eller en validator installeret for at virke? Nej. Når redocly/spectral eller oasdiff kan køre, bruger den dem og rapporterer kommandoen og resultatet. Når de ikke kan, siger den det eksplicit og kører et defineret selvtjek som fallback — alle $ref'er løses op, unikke operationId'er, hver stiparameter erklæret, hvert svar har en beskrivelse. Den springer aldrig stille et tjek over.

Er benchmarken reproducerbar? Ja. Syv opgaver, to arme, mekanisk scoring hvor muligt, og den forhåndsregistrerede grundsandhed er tjekket ind i repoet under bench/ground-truth/. Den fulde metode, detaljer per fund og T6-tabet og T4-integritetsfodnoten er alle i bench/results/verdict.md — intet er skjult.