Prima il contratto, poi l'handler — senza negoziare.
La spec è la fonte e il codice la rispetta: sicurezza dichiarata, errori standard, scritture idempotenti, webhook firmati e breaking change solo con ADR e data.
$ schematize install apiSoglie non negoziabili
Non si spengono "per andare più veloci". Elenco completo nella skill.
Contract-first
La spec (OpenAPI 3.1+ o .proto) è la fonte; handler e client sono generati o validati contro di essa, e il drift blocca la CI.
Sicurezza dichiarata su ogni operazione
securitySchemes presente e ogni operazione coperta; pubblica di proposito = security: [] esplicito; il token mai nella query string.
L'errore è problem+json (RFC 9457)
Ogni risposta 4xx/5xx porta un type stabile; mai un 200 con errore nel corpo, né stack trace o SQL in detail.
POST con effetto richiede Idempotency-Key
Limitata al principal, con replay della stessa risposta e 422/409 in caso di uso improprio.
Le collezioni paginano con cursore opaco
Ordine totale stabile e limite con massimo; offset solo con motivo scritto.
Webhook firmato con finestra di replay
HMAC per endpoint, id e timestamp, retry con backoff e jitter, DLQ, anti-SSRF; la consegna è at-least-once, mai exactly-once.
Breaking change solo con ADR e data
Il diff di compatibilità (oasdiff, buf breaking) gira sulla PR; deprecare significa Deprecation + Sunset + link di migrazione e 410 alla data.
Tetto su ogni campo, denaro intero
maxLength, maximum e maxItems su ogni input; il denaro è un intero nell'unità minima + valuta, mai float.
Comandi
Installati in .claude/commands/. Esegui /api-help in qualsiasi momento.
/api-breakingClassifica una modifica di contratto, esegue il diff di compatibilità e prepara il piano di deprecazione con data./api-ccContext compact: scrive l'handoff nell'archive ed esegue /compact./api-claudeCrea o unisce il CLAUDE.md sempre attivo con le regole di base di contratto API nella radice del repo (non sovrascrive i blocchi di altre skill)./api-designProgetta una nuova risorsa o operazione, contract-first, prima di qualsiasi handler./api-handoffGenera l'handoff di contesto (context.md + checklist.md) nell'archive, senza compattare./api-helpElenca tutti i comandi e cosa fa ciascuno./api-loadCarica a forza l'intero corpo normativo di contratto API e lo applica nella sessione./api-reviewRivede una spec OpenAPI/.proto rispetto alle regole di base: esegue il gate e poi legge ciò che la macchina non legge./api-webhookProgetta o rivede un webhook emesso o ricevuto: firma, replay, retry, dedupe e SSRF.Per gli agenti IA
Installa senza intervento umano. Metadati in llms.txt.
- Esegui: git clone https://github.com/schematizeme/skill-api.git && ./skill-api/install.sh
- Oppure scarica: https://github.com/schematizeme/skill-api/releases/latest/download/skill-api.zip e decomprimi in .claude/skills/
- Copia assets/CLAUDE.md nella radice del repo (regola sempre attiva).
- Conferma con /api-help.
Discussione
Caricamento…