API Conventions
Regole REST interne che Claude applica nella progettazione di endpoint: forma URL, data/error/meta, 422.
Promosso
Cosa fa
Una skill di riferimento che carica un set fisso di convenzioni REST quando Claude scrive o revisiona endpoint API: URL di risorse in kebab-case plurale con massimo due livelli di annidamento, un envelope di risposta data/error/meta obbligatorio, una tabella di codici di stato che indirizza i fallimenti della logica di business a 422, autenticazione Bearer con un opt-out @public, e versioning del percorso /api/v1. Si attiva su richieste di progettare un nuovo endpoint, scegliere un formato di risposta o revisionare la forma e le risposte di errore di una route esistente. Le regole sono hardcoded e opinabili, quindi forkare SKILL.md e sostituire con i propri standard prima di usarla su un progetto reale.
Rapporto di test
Installato in una HOME temporanea=$(mktemp -d) e confermato che SKILL.md è finito in ~/.claude/skills/api-conventions/SKILL.md; frontmatter analizzato con yaml.safe_load (name, descrizione di 273 caratteri, allowed-tools Read/Grep/Glob), il corpo è di 1231 caratteri che non fanno riferimento a file esterni, e un grep per curl|base64|eval|http://|/Users/ non ha trovato nulla. Stesso task due volte — "progetta endpoint per elencare i coupon di un cliente e riscattarne uno" — baseline.md vs skill.md nel blocco note: la baseline ha restituito un oggetto nudo {"coupons":[...],"page","per_page","total"}, POST /api/coupons/{code}/redeem che restituiva 200, e 409/410 per già riscattato/scaduto; la versione della skill ha restituito {"data":[...],"error":null,"meta":{page,limit,total}} su ogni risposta, ha spostato l'azione a POST /api/v1/coupons/{code}/redemptions che restituiva 201, ha collassato 409 e 410 in 422, ha aggiunto un caso di proprietà 403, e ha reso l'autenticazione esplicita come Bearer + un'annotazione @public sull'unico endpoint aperto. Frasi di attivazione che ho giudicato valide: "aggiungi un endpoint REST per elencare le fatture di un utente — come dovrebbero essere l'URL e il corpo della risposta?", "revisiona questo file di route Express e dimmi se le risposte di errore sono corrette", "stiamo progettando una nuova API pubblica per gli ordini — quale codice di stato per un errore di validazione?"; giudicate non valide: "scrivi un client Python che chiama l'API Stripe e riprova su 429" (consumo, non progettazione) e "l'endpoint /users restituisce 500, aiutami a trovare il null deref" (debugging runtime, non formato) — 5/5 corretto. Avvertenza reale: è una demo di corso, quindi le convenzioni sono hardcoded allo stile di un autore e metà della prosa del corpo è cinese.
Testato il: 2026-07-21 · Claude Code 2.x (agent harness)
Installazione
git clone --depth 1 https://github.com/huangjia2019/claude-code-engineering.git /tmp/api-conventions-src
mkdir -p ~/.claude/skills
cp -R /tmp/api-conventions-src/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions ~/.claude/skills/api-conventions
# Single self-contained SKILL.md (~1.7KB), no scripts, no deps, no API keys.
# Source repo is a Chinese course companion ("Claude Code 工程化实战") with 8+ demo skills;
# this slug is the 01-reference-skill example. Parts of the SKILL.md body (response-format
# and status-code notes) are written in Chinese; the rules themselves are language-neutral.
# IMPORTANT: the description says "conventions for this project" but the rules are the course
# author's, not yours. Edit ~/.claude/skills/api-conventions/SKILL.md to match your real
# standards, or it will push /api/v1, data/error/meta envelopes and 422 onto every codebase.
# frontmatter sets allowed-tools: Read, Grep, Glob (read-only). Comandi e prompt di esempio
/api-conventionsRegole REST interne che Claude applica nella progettazione di endpoint: forma URL, data/error/meta, 422.
Gli skill si attivano con richieste in linguaggio naturale, senza comandi da ricordare. Dopo l'installazione, prompt come questi lo attivano (in inglese):
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards