La skill Claude che verifica da sola la sua spec OpenAPI

Chiedi a Claude di progettare un'API e ottieni qualcosa che sembra corretto: nomi al plurale, un parametro di paginazione, un prefisso di versione. Poi leggi con attenzione e un endpoint usa page_size dove tutte le altre liste usano limit, un errore di validazione è documentato come 500, e la spec include un nullable: true che non esiste in OpenAPI 3.1. Ogni errore è piccolo. Insieme sono la differenza tra un'API che funziona e un'API che resta coerente nel tempo — e niente in un prompt "ecco i principi" forza il secondo risultato.

Il risultato è api-discipline, e il punto non è che conosce le convenzioni REST — lo fa ogni skill di questa nicchia. Il punto è che verifica il proprio output prima di restituirlo: OpenAPI 3.1 pulito al validatore, una passata obbligatoria di coerenza tra endpoint, e un diff di breaking change a ogni modifica. È gratis e con licenza MIT: github.com/Skillproofdev/api-discipline.

Il vuoto: tutti insegnano i principi, nessuno li fa rispettare

Prima di scrivere una riga abbiamo passato in rassegna 84 skill di API design e OpenAPI nel nostro indice di 16.682 skill più l'ecosistema web standalone. Lo schema è coerente. Il repo più grande (37,6k stelle) è un manuale di concetti a enforcement zero. Il meglio ingegnerizzato (10,5k stelle) nomina un linter e si ferma lì.

E questo conta per quello che potevamo affermare onestamente. Un output pulito al validatore da solo è già uno spazio risolto e competitivo — la skill da 10,5k stelle ci arriva. Dire "usiamo anche noi un linter" sarebbe stato solo rumore. Quindi abbiamo cercato quello che nessuno applica, e abbiamo trovato quattro cose che non esistevano in nessuna delle 84:

1. Un audit di coerenza tra endpoint come passata obbligatoria. Dieci controlli definiti — casing, pluralizzazione, un unico schema di errore condiviso, parametri di paginazione identici, formati id/timestamp uniformi, pattern operationId, stesso codice di stato per la stessa azione — eseguiti su ogni endpoint prima della consegna. Ogni concorrente ha, al massimo, un bullet "sii coerente".
2. Disciplina sui breaking change che scatta a ogni modifica. Ogni modifica alla spec riceve una passata enumerata di breaking change, supportata meccanicamente da oasdiff breaking quando disponibile. Lo strumento è maturo; nessuna skill esaminata lo collega.
3. Semantica HTTP come regole, non nozionismo. PUT sostituisce, PATCH modifica parzialmente, POST crea con 201 + Location, DELETE restituisce 204 — imposti con una tabella di codici di stato, non elencati come "concetti da conoscere".
4. Un contratto d'output per review/estensione. "Rivedi questa spec" restituisce finding legati alla checklist con posizioni e correzioni; "aggiungi un endpoint" restituisce un diff che eredita le convenzioni della spec esistente più un blocco di breaking change. I concorrenti definiscono solo l'output greenfield.

Questo è il terreno scoperto: non la validazione, ma l'audit che gira dopo la validazione, più un benchmark pubblicato a sostegno.

Il benchmark: misurato, con le perdite lasciate dentro

Sette task — due design greenfield, due estensioni di spec, due review di spec difettose con 22 violazioni piantate tra loro, una domanda sulle convenzioni. Ogni task è girato due volte: un agente Claude Sonnet a secco, uno che legge prima il SKILL.md, prompt identici. Le spec sono state valutate meccanicamente con redocly lint e spectral lint, le modifiche confrontate con oasdiff breaking, e i catch delle violazioni piantate giudicati da agenti verificatori indipendenti.

Metrica (più basso è meglio)	base	skill
Errori validatore, greenfield (redocly)	18	0
Violazioni di coerenza, tutti e 4 i task di design	6	0
Errori di semantica HTTP, tutti e 4 i task di design	3	0
Violazioni piantate colte, review T6 (più alto meglio)	10/10	9/10

Misurato il 10/07/2026 con Redocly CLI 2.38.0, Spectral 6.16.1, e oasdiff 1.23.0. Il dettaglio completo per ogni finding è in bench/results/verdict.md.

Il vuoto sul validatore è una storia pulita: entrambi i run a secco hanno emesso nullable: true di OpenAPI 3.0 in documenti dichiarati openapi: 3.1.0 — un errore strutturale in 3.1, che usa type: [x, 'null']. Dodici occorrenze nel primo task greenfield, sei nel secondo. Il run con skill ha usato la forma 3.1 ovunque e ha validato pulito. Le vittorie su coerenza e semantica hanno la stessa forma: i run a secco hanno prodotto endpoint con verbo nel path (/tasks/{id}/complete), un secondo schema di errore ad hoc accanto a quello condiviso, e una creazione che restituiva 200 invece di 201. Il run con skill ha modellato le azioni come sotto-risorse nominali e riusato un unico schema di errore ovunque — 0 su tutti e quattro i task di design.

Dove la skill ha perso — e un risultato di cui non ci prendiamo il merito

Due note oneste, perché la nostra metodologia richiede di mettere le perdite accanto alle vittorie.

La skill ha perso T6 per una violazione piantata. Sulla review incentrata sulla semantica, la passata libera dell'agente a secco ha percorso ogni operazione in modo esaustivo e ha colto un 201 Created su POST /articles senza header Location. La review dell'agente con skill, organizzata attorno alla checklist di coerenza, ha segnalato tutti e quattro i difetti di metodo HTTP e tutti e cinque i seed di coerenza ma non ha scansionato ogni 201 per il suo Location — 9/10 contro 10/10. La review strutturata ha coperto meno di quanto una lettura esaustiva abbia colto. Ora è corretto nella checklist con una riga esplicita "ogni 201 ha Location".

Un risultato sui breaking change è escluso dal dato principale. Sul task di estensione della spec, l'agente con skill ha riferito di aver visto un suggerimento di ground truth trapelato nel file del task ("entrambe le modifiche sono breaking") prima dell'analisi — uno scivolone di protocollo, dato che il braccio con skill dovrebbe leggere solo il SKILL.md. Quindi quel risultato non è rivendicato come una vittoria indipendente, anche se sembra buono sulla carta. Due cose rendono comunque solido il risultato di fondo: il braccio a secco, che non legge mai il file del task, ha concluso indipendentemente che entrambe le modifiche erano breaking; e oasdiff ha confermato meccanicamente la superficie breaking a prescindere da cosa credesse ciascun agente. I risultati principali poggiano su validazione, coerenza e semantica — nessuna delle quali è toccata dalla fuga.

Installazione

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

Riavvia Claude Code. Si attiva su "progetta un'API," "aggiungi/estendi un endpoint," "rivedi questa spec OpenAPI," e domande sulle convenzioni REST — e resta fuori dai piedi per lavoro solo-GraphQL, codegen di SDK client, e test di sicurezza API. Fa parte della famiglia con token-discipline, che taglia quanto costa il lavoro multi-step, e research-discipline, che taglia quanto la ricerca sbaglia — questa taglia quanto i tuoi contratti API deviano.

FAQ

Una skill da 10,5k stelle produce già OpenAPI valido. Perché questa? Perché valido non è lo stesso di coerente. Un linter cattura un $ref rotto; non cattura un endpoint che pagina con page_size mentre tutti gli altri usano limit, o una creazione che restituisce 200. Quell'audit di coerenza tra endpoint è il terreno scoperto — è ciò che le skill popolari non applicano, ed è dove i run a secco hanno accumulato 6 violazioni contro lo 0 della skill.

Gestisce anche modifiche a una spec esistente, non solo il design greenfield? Sì, e le tratta in modo diverso. I nuovi endpoint aggiunti a una spec esistente ereditano le sue convenzioni anche quando confliggono con i default della skill — la coerenza con il contratto da cui dipendono altre persone batte le preferenze della skill. Ogni modifica riceve anche una passata enumerata di breaking change, supportata da oasdiff breaking quando lo strumento è disponibile.

Ha bisogno di oasdiff o di un validatore installati per funzionare? No. Quando redocly/spectral o oasdiff possono girare, li usa e riporta comando e risultato. Quando non possono, lo dice esplicitamente ed esegue un fallback di autocontrollo definito — tutti i $ref si risolvono, operationId univoci, ogni parametro di path dichiarato, ogni risposta ha una descrizione. Non salta mai un controllo in silenzio.

Il benchmark è riproducibile? Sì. Sette task, due bracci, valutazione meccanica dove possibile, e la ground truth pre-registrata è nel repo sotto bench/ground-truth/. Il metodo completo, il dettaglio per ogni finding, e la perdita su T6 con la nota di integrità su T4 sono tutti in bench/results/verdict.md — niente è nascosto.