Primero el contrato, luego el handler: sin negociar.
La spec es la fuente y el código la obedece: seguridad declarada, errores estándar, escritura idempotente, webhooks firmados y cambios incompatibles solo con ADR y fecha.
$ schematize install apiPisos innegociables
No se apagan "para ir más rápido". Lista completa en la skill.
Contract-first
La spec (OpenAPI 3.1+ o .proto) es la fuente; handlers y clientes se generan o validan contra ella, y el drift bloquea la CI.
Seguridad declarada en cada operación
securitySchemes presente y cada operación cubierta; pública a propósito es un security: [] explícito; el token nunca va en la query string.
El error es problem+json (RFC 9457)
Toda respuesta 4xx/5xx lleva un type estable; nunca un 200 con error en el cuerpo ni stack trace o SQL en detail.
POST con efecto exige Idempotency-Key
Acotada al principal, con replay de la misma respuesta y 422/409 ante un uso indebido.
La colección pagina con cursor opaco
Orden total estable y límite con máximo; offset solo con motivo escrito.
Webhook firmado y con ventana de replay
HMAC por endpoint, id y timestamp, reintento con backoff y jitter, DLQ, anti-SSRF; la entrega es at-least-once, nunca exactly-once.
Cambio incompatible solo con ADR y fecha
El diff de compatibilidad (oasdiff, buf breaking) corre en el PR; deprecar es Deprecation + Sunset + enlace de migración y 410 en la fecha.
Tope en cada campo, dinero entero
maxLength, maximum y maxItems en toda entrada; el dinero es un entero en la unidad menor + moneda, nunca float.
Comandos
Instalados en .claude/commands/. Usa /api-help en cualquier momento.
/api-breakingClasifica un cambio de contrato, ejecuta el diff de compatibilidad y arma el plan de deprecación con fecha./api-ccContext compact: guarda el handoff en el archive y ejecuta /compact./api-claudeCrea o fusiona el CLAUDE.md siempre activo del piso de contrato de API en la raíz del repo (no sobrescribe bloques de otras skills)./api-designDiseña un recurso u operación nuevos, contract-first, antes de cualquier handler./api-handoffGenera el handoff de contexto (context.md + checklist.md) en el archive, sin compactar./api-helpLista todos los comandos y lo que hace cada uno./api-loadCarga a la fuerza todo el cuerpo normativo de contrato de API y empieza a aplicarlo en la sesión./api-reviewRevisa la spec OpenAPI/.proto contra el piso: ejecuta el gate y luego lee lo que la máquina no lee./api-webhookDiseña o revisa un webhook emitido o recibido: firma, replay, reintento, dedupe y SSRF.Para agentes de IA
Instala sin intervención humana. Metadatos en llms.txt.
- Ejecuta: git clone https://github.com/schematizeme/skill-api.git && ./skill-api/install.sh
- O descarga: https://github.com/schematizeme/skill-api/releases/latest/download/skill-api.zip y descomprime en .claude/skills/
- Copia assets/CLAUDE.md a la raíz del repo (regla siempre activa).
- Confirma con /api-help.
Discusión
Cargando…