Le skill Claude qui audite sa propre spec OpenAPI

Demandez à Claude de designer une API et vous obtenez quelque chose qui a l'air correct : noms au pluriel, un paramètre de pagination, un préfixe de version. Puis vous lisez de plus près et un endpoint utilise page_size là où toutes les autres listes utilisent limit, une erreur de validation est documentée comme un 500, et la spec livre un nullable: true qui n'existe pas en OpenAPI 3.1. Chaque erreur est petite. Ensemble, elles font la différence entre une API qui fonctionne et une API qui reste cohérente face au changement — et rien dans un prompt « voici les principes » n'impose la seconde.

Le résultat s'appelle api-discipline, et l'important n'est pas qu'il connaisse les conventions REST — tous les skills de ce créneau les connaissent. L'important, c'est qu'il vérifie sa propre sortie avant de vous la rendre : de l'OpenAPI 3.1 propre pour le validateur, une passe de cohérence inter-endpoints obligatoire, et un diff de changements cassants à chaque modification. Il est gratuit et sous licence MIT : github.com/Skillproofdev/api-discipline.

Le vide : tout le monde enseigne les principes, personne ne les impose

Avant d'écrire une ligne, nous avons passé en revue 84 skills de design d'API et d'OpenAPI dans notre index de 16 682 skills, plus l'écosystème web autonome. Le schéma est constant. Le plus gros dépôt (37 600 étoiles) est un manuel de concepts, sans aucune application. Le mieux conçu (10 500 étoiles) nomme un linter et s'arrête là.

Et ça compte pour ce que nous pouvions honnêtement revendiquer. Une sortie propre pour le validateur est déjà, à elle seule, un espace saturé et concurrentiel — le skill à 10 500 étoiles vous y mène. Annoncer « nous aussi on lance un linter » aurait été du bruit. Nous avons donc cherché ce que personne n'impose, et trouvé quatre choses qui n'existaient dans aucun des 84 :

1. Un audit de cohérence inter-endpoints comme passe obligatoire. Dix contrôles définis — casse, pluriel, un schéma d'erreur partagé, des paramètres de pagination identiques, des formats d'id/timestamp uniformes, un motif d'operationId, même action → même code de statut — exécutés sur chaque endpoint avant livraison. Chaque concurrent a, au mieux, une puce « soyez cohérent ».
2. Une discipline de changements cassants qui se déclenche à chaque modification. Chaque modification de spec reçoit une passe de changements cassants énumérée, appuyée mécaniquement par oasdiff breaking quand c'est disponible. L'outillage est mature ; aucun skill étudié ne le connecte.
3. La sémantique HTTP comme règles, pas comme culture générale. PUT remplace, PATCH modifie partiellement, POST crée avec 201 + Location, DELETE renvoie 204 — imposé avec une table de codes de statut, pas listé comme « concepts à connaître ».
4. Un contrat de sortie pour la relecture et l'extension. « Relis cette spec » renvoie des constats rattachés à la checklist avec emplacements et corrections ; « ajoute un endpoint » renvoie un diff qui hérite des conventions de la spec existante plus un bloc de changements cassants. Les concurrents ne définissent que la sortie en création pure.

C'est le terrain que personne ne conteste : pas la validation, mais l'audit qui vient après la validation, plus un benchmark publié pour l'étayer.

Le benchmark : mesuré, pertes incluses

Sept tâches — deux designs en création pure, deux extensions de spec, deux relectures de specs défectueuses avec 22 violations implantées à elles deux, une question de convention. Chacune a tourné deux fois : un agent Claude Sonnet nu, un lisant le SKILL.md d'abord, prompts identiques. Les specs ont été notées mécaniquement avec redocly lint et spectral lint, les modifications diffées avec oasdiff breaking, et les violations implantées repérées jugées par des agents vérificateurs indépendants.

Métrique (plus bas = mieux)	base	skill
Erreurs de validateur, création pure (redocly)	18	0
Violations de cohérence, les 4 tâches de design	6	0
Erreurs de sémantique HTTP, les 4 tâches de design	3	0
Violations implantées repérées, relecture T6 (plus haut = mieux)	10/10	9/10

Mesuré le 2026-07-10 avec Redocly CLI 2.38.0, Spectral 6.16.1 et oasdiff 1.23.0. Le détail complet par constat est dans bench/results/verdict.md.

L'écart de validateur raconte une histoire limpide : les deux exécutions nues ont émis un nullable: true d'OpenAPI 3.0 dans des documents déclarés openapi: 3.1.0 — une erreur structurelle en 3.1, qui utilise type: [x, 'null']. Douze occurrences dans la première tâche de création pure, six dans la seconde. L'exécution avec skill a utilisé la forme 3.1 tout du long et validé sans erreur. Les victoires de cohérence et de sémantique suivent le même schéma : les exécutions nues ont livré des endpoints avec verbe dans le chemin (/tasks/{id}/complete), un second schéma d'erreur improvisé à côté du schéma partagé, et une création renvoyant 200 au lieu de 201. L'exécution avec skill a modélisé les actions comme des sous-ressources nommées et réutilisé un seul schéma d'erreur partout — 0 sur les quatre tâches de design.

Là où le skill a perdu — et un résultat dont nous ne nous attribuons pas le mérite

Deux notes honnêtes, parce que notre méthodologie exige que les pertes soient publiées à côté des gains.

Le skill a perdu T6 d'une violation implantée. Sur la relecture centrée sémantique, la passe libre de l'agent nu a parcouru chaque opération de façon exhaustive et attrapé un 201 Created sur POST /articles sans en-tête Location. La relecture de l'agent avec skill, organisée autour de la checklist de cohérence, a signalé les quatre défauts de méthode HTTP et les cinq violations de cohérence implantées, mais n'a pas balayé chaque 201 pour vérifier son Location — 9/10 contre 10/10. Une relecture structurée a moins bien couvert que ce qu'une lecture exhaustive a attrapé. C'est désormais corrigé dans la checklist avec une ligne explicite « chaque 201 a un Location ».

Un résultat sur les changements cassants est exclu du bilan principal. Sur la tâche d'extension de spec, l'agent avec skill a signalé avoir vu un indice de vérité terrain qui avait fuité dans le fichier de tâche (« les deux changements sont cassants ») avant d'analyser — un manquement de protocole, puisque le bras avec skill ne devrait lire que le SKILL.md. Ce résultat n'est donc pas revendiqué comme une victoire indépendante, même s'il a l'air bon sur le papier. Deux éléments rendent le constat sous-jacent solide malgré tout : le bras nu, qui ne lit jamais le fichier de tâche, a conclu indépendamment que les deux changements étaient cassants ; et oasdiff a confirmé mécaniquement la surface de rupture, quoi que l'un ou l'autre agent ait cru. Les revendications principales reposent sur la validation, la cohérence et la sémantique — rien de tout ça n'est touché par la fuite.

Installation

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

Redémarrez Claude Code. Il se déclenche sur « design an API », « add/extend an endpoint », « review this OpenAPI spec » et les questions de convention REST — et reste en retrait pour le travail GraphQL pur, la génération de SDK client et les tests de sécurité d'API. Il rejoint token-discipline, qui réduit ce que le travail à plusieurs étapes coûte, et research-discipline, qui réduit ce qu'une recherche se trompe — celui-ci réduit ce vers quoi vos contrats d'API dérivent.

FAQ

Un skill à 10 500 étoiles produit déjà de l'OpenAPI valide. Pourquoi celui-ci ? Parce que valide n'est pas synonyme de cohérent. Un linter attrape un $ref cassé ; il n'attrape pas un endpoint qui pagine avec page_size pendant que tous les autres utilisent limit, ni une création qui renvoie 200. Cet audit de cohérence inter-endpoints est le terrain que personne ne conteste — c'est ce que les skills populaires n'imposent pas, et c'est là que les exécutions nues ont accumulé 6 violations contre 0 pour le skill.

Gère-t-il les modifications d'une spec existante, pas seulement la création pure ? Oui, et il les traite différemment. Les nouveaux endpoints ajoutés à une spec existante héritent de ses conventions même quand elles contredisent celles par défaut du skill — la cohérence avec le contrat dont dépendent d'autres personnes prime sur les préférences du skill. Chaque modification reçoit aussi une passe de changements cassants énumérée, appuyée par oasdiff breaking quand l'outil est disponible.

A-t-il besoin d'oasdiff ou d'un validateur installé pour fonctionner ? Non. Quand redocly/spectral ou oasdiff peuvent tourner, il les utilise et rapporte la commande et le résultat. Quand ils ne peuvent pas, il le dit explicitement et exécute un repli d'auto-vérification défini — tous les $ref se résolvent, operationId uniques, chaque paramètre de chemin déclaré, chaque réponse a une description. Il ne saute jamais un contrôle en silence.

Le benchmark est-il reproductible ? Oui. Sept tâches, deux bras, notation mécanique quand c'est possible, et la vérité terrain pré-enregistrée est versionnée dans le dépôt sous bench/ground-truth/. La méthode complète, le détail par constat, ainsi que la perte T6 et la note d'intégrité T4, sont tous dans bench/results/verdict.md — rien n'est caché.