De Claude-skill die zijn eigen OpenAPI-spec controleert

Vraag Claude om een API te ontwerpen en je krijgt iets dat er goed uitziet: meervoudsvormen, een pagination-param, een versie-prefix. Lees je goed door, dan gebruikt één endpoint page_size waar elke andere lijst limit gebruikt, staat een validatiefout gedocumenteerd als een 500, en bevat de spec een nullable: true die in OpenAPI 3.1 niet bestaat. Elke fout is klein. Samen zijn ze het verschil tussen een API die werkt en een API die consistent blijft onder verandering — en niets in een "hier zijn de principes"-prompt dwingt dat tweede af.

Het resultaat is api-discipline, en het punt is niet dat hij REST-conventies kent — dat doet elke skill in deze niche. Het punt is dat hij zijn eigen output checkt voordat hij die teruggeeft: validator-schone OpenAPI 3.1, een verplichte cross-endpoint-consistentiepass, en een breaking-change-diff bij elke wijziging. Gratis en MIT-licensed: github.com/Skillproofdev/api-discipline.

Het gat: iedereen leert de principes, niemand handhaaft ze

Voordat we een regel schreven, bekeken we 84 API-ontwerp- en OpenAPI-skills in onze index van 16.682 skills plus het losstaande web-ecosysteem. Het patroon is consistent. De grootste repo (37,6k sterren) is een begrippen-leerboek zonder handhaving. De best gebouwde (10,5k sterren) noemt een linter en stopt daar.

En dat is belangrijk voor wat we eerlijk konden claimen. Validator-schone output alleen is al een opgelost, competitief terrein — de skill met 10,5k sterren brengt je daar al. "Wij draaien ook een linter" zou ruis zijn geweest. Dus zochten we naar wat niemand afdwingt, en vonden vier dingen die in geen enkele van de 84 voorkwamen:

1. Een cross-endpoint-consistentie-audit als verplichte pass. Tien vaste checks — hoofdlettergebruik, meervoudsvorming, één gedeeld errorschema, identieke pagination-params, uniform id-/timestampformaat, operationId-patroon, dezelfde-actie-dezelfde-statuscode — draaien over elk endpoint vóór oplevering. Elke concurrent heeft hoogstens één "wees consistent"-punt.
2. Breaking-change-discipline die afgaat bij elke wijziging. Elke spec-wijziging krijgt een opgesomde breaking-change-pass, mechanisch onderbouwd met oasdiff breaking waar beschikbaar. De tooling is volwassen; geen enkele bekeken skill koppelt hem aan.
3. HTTP-semantiek als regels, niet als weetjes. PUT vervangt, PATCH doet gedeeltelijk, POST maakt aan met 201 + Location, DELETE geeft 204 — afgedwongen met een statuscodetabel, niet opgesomd als "concepten om te kennen."
4. Een review-/uitbreidingsoutputcontract. "Review deze spec" geeft bevindingen terug gekoppeld aan de checklist met locaties en fixes; "voeg een endpoint toe" geeft een diff terug die de conventies van de bestaande spec overneemt plus een breaking-changes-blok. Concurrenten definiëren alleen greenfield-output.

Dat is het onbetwiste terrein: niet validatie, maar de audit die na validatie draait, plus een gepubliceerde benchmark om het te onderbouwen.

De benchmark: gemeten, met de verliezen erin gelaten

Zeven taken — twee greenfield-ontwerpen, twee spec-uitbreidingen, twee reviews van gebrekkige specs met 22 ingebouwde overtredingen samen, één conventievraag. Elke taak draaide twee keer: één Claude Sonnet-agent kaal, één die eerst de SKILL.md leest, identieke prompts. Specs werden mechanisch gescoord met redocly lint en spectral lint, wijzigingen gediffed met oasdiff breaking, en ingebouwde-overtredingen-vangsten beoordeeld door onafhankelijke verifier-agents.

Metriek (lager is beter)	base	skill
Validatorfouten, greenfield (redocly)	18	0
Consistentie-overtredingen, alle 4 ontwerptaken	6	0
HTTP-semantiekfouten, alle 4 ontwerptaken	3	0
Ingebouwde overtredingen gevangen, T6-review (hoger beter)	10/10	9/10

Gemeten op 2026-07-10 met Redocly CLI 2.38.0, Spectral 6.16.1 en oasdiff 1.23.0. Volledige details per bevinding staan in bench/results/verdict.md.

Het validatorgat is één helder verhaal: beide kale runs zetten OpenAPI 3.0 nullable: true in documenten die verklaard staan als openapi: 3.1.0 — een structurele fout in 3.1, dat type: [x, 'null'] gebruikt. Twaalf keer in de eerste greenfield-taak, zes keer in de tweede. De skill-run gebruikte overal de 3.1-vorm en valideerde schoon. De consistentie- en semantiekwinsten hebben dezelfde vorm: de kale runs leverden endpoints met werkwoorden in het pad (/tasks/{id}/complete), een tweede ad-hoc errorschema naast het gedeelde, en een create die 200 teruggaf in plaats van 201. De skill-run modelleerde acties als naamwoord-subresources en hergebruikte overal één errorschema — 0 over alle vier de ontwerptaken.

Waar de skill verloor — en één resultaat waar we geen krediet voor nemen

Twee eerlijke kanttekeningen, want onze methodologie eist de verliezen naast de winsten.

De skill verloor T6 met één ingebouwde overtreding. Bij de semantiek-zware review liep de vrije pass van de kale agent elke operatie uitputtend na en ving een 201 Created op POST /articles zonder Location-header. De review van de skill-agent, georganiseerd rond de consistentiechecklist, markeerde alle vier de HTTP-methode-defecten en alle vijf de consistentie-overtredingen maar scande niet elke 201 op zijn Location — 9/10 tegen 10/10. Gestructureerde review dekte minder dan een uitputtende lezing ving. Dat is nu gefixt in de checklist met een expliciete "elke 201 heeft een Location"-regel.

Eén breaking-change-resultaat is uitgesloten van de hoofdclaim. Bij de spec-uitbreidingstaak meldde de skill-agent dat hij een ground-truth-hint had gezien die in het taakbestand was gelekt ("beide wijzigingen zijn breaking") vóór de analyse — een protocolfout, want de skill-arm zou alleen de SKILL.md mogen lezen. Dat resultaat wordt dus niet als onafhankelijke winst geclaimd, ook al ziet het er goed uit op papier. Twee dingen maken de onderliggende bevinding toch robuust: de kale arm, die het taakbestand nooit leest, kwam onafhankelijk tot de conclusie dat beide wijzigingen breaking waren; en oasdiff bevestigde mechanisch het breaking-oppervlak, los van wat beide agents dachten. De hoofdclaims rusten op validatie, consistentie en semantiek — geen daarvan raakt de lek.

Installatie

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

Herstart Claude Code. Hij triggert op "ontwerp een API," "voeg een endpoint toe/breid uit," "review deze OpenAPI-spec," en vragen over REST-conventies — en blijft weg bij pure GraphQL-werk, client-SDK-codegen en API-securitytesten. Hij hoort bij token-discipline, dat verlaagt wat werk in meerdere stappen kost, en research-discipline, dat verlaagt wat research fout heeft — deze verlaagt waar je API-contracten naar afdrijven.

FAQ

Een skill met 10,5k sterren levert al geldige OpenAPI. Waarom dan deze? Omdat geldig niet hetzelfde is als consistent. Een linter vangt een kapotte $ref; hij vangt niet dat één endpoint pagineert met page_size terwijl de rest limit gebruikt, of dat een create 200 teruggeeft. Die cross-endpoint-consistentie-audit is het onbetwiste terrein — het is wat de populaire skills niet afdwingen, en het is waar de kale runs 6 overtredingen scoorden tegen de skill's 0.

Werkt hij ook op wijzigingen aan een bestaande spec, niet alleen greenfield-ontwerp? Ja, en hij behandelt ze anders. Nieuwe endpoints die aan een bestaande spec worden toegevoegd, nemen diens conventies over, zelfs als die botsen met de standaardvoorkeuren van de skill — consistentie met het contract waar anderen op vertrouwen wint van de voorkeuren van de skill. Elke wijziging krijgt ook een opgesomde breaking-change-pass, onderbouwd met oasdiff breaking wanneer de tool beschikbaar is.

Heeft hij oasdiff of een validator nodig om te werken? Nee. Wanneer redocly/spectral of oasdiff kunnen draaien, gebruikt hij ze en rapporteert hij het commando en resultaat. Kunnen ze niet, dan zegt hij dat expliciet en draait hij een vastgelegde zelfcheck-fallback — alle $ref's opgelost, unieke operationId's, elke padparameter gedeclareerd, elke response met een beschrijving. Hij slaat de check nooit stilletjes over.

Is de benchmark reproduceerbaar? Ja. Zeven taken, twee armen, mechanische scoring waar mogelijk, en de vooraf vastgelegde ground truth staat in de repo onder bench/ground-truth/. De volledige methode, details per bevinding en de T6-verlies- en T4-integriteitsvoetnoot staan allemaal in bench/results/verdict.md — niets is verborgen.