API Conventions
Reglas REST internas que Claude aplica al diseñar endpoints: forma de URL, data/error/meta, 422
Probado · Funciona
Qué hace
Una habilidad de referencia que carga un conjunto fijo de convenciones REST cuando Claude escribe o revisa endpoints de API: URLs de recursos en kebab-case plural con un máximo de dos niveles de anidamiento, un envoltorio de respuesta obligatorio data/error/meta, una tabla de códigos de estado que dirige los fallos de lógica de negocio a 422, autenticación Bearer con una opción de exclusión @public, y versionado de rutas /api/v1. Se activa en solicitudes para diseñar un nuevo endpoint, elegir un formato de respuesta o revisar la forma y las respuestas de error de una ruta existente. Las reglas están codificadas y son opinables, así que bifurque el SKILL.md e inserte sus propios estándares antes de usarlo en un proyecto real.
Informe de la prueba
Instalado en un HOME temporal=$(mktemp -d) y confirmado que SKILL.md se ubicó en ~/.claude/skills/api-conventions/SKILL.md; el frontmatter se analizó con yaml.safe_load (name, descripción de 273 caracteres, allowed-tools Read/Grep/Glob), el cuerpo tiene 1231 caracteres referenciando cero archivos externos, y un grep para curl|base64|eval|http://|/Users/ no encontró nada. Misma tarea dos veces — "diseñar endpoints para listar los cupones de un cliente y canjear uno" — baseline.md vs skill.md en el bloc de notas: la línea base devolvió un objeto simple {"coupons":[...],"page","per_page","total"}, POST /api/coupons/{code}/redeem devolviendo 200, y 409/410 para ya canjeado/expirado; la versión de la habilidad devolvió {"data":[...],"error":null,"meta":{page,limit,total}} en cada respuesta, movió la acción a POST /api/v1/coupons/{code}/redemptions devolviendo 201, colapsó 409 y 410 en 422, añadió un caso de propiedad 403, e hizo explícita la autenticación como Bearer + una anotación @public en el único endpoint abierto. Frases de activación que juzgué válidas: "añadir un endpoint REST para listar las facturas de un usuario — ¿cómo deberían ser la URL y el cuerpo de la respuesta?", "revisar este archivo de ruta Express y decirme si las respuestas de error son correctas", "estamos diseñando una nueva API pública de pedidos — ¿qué código de estado para un fallo de validación?"; juzgadas no válidas: "escribir un cliente Python que llame a la API de Stripe y reintente en 429" (consumiendo, no diseñando) y "el endpoint /users devuelve 500, ayúdame a encontrar el null deref" (depuración en tiempo de ejecución, no formato) — 5/5 correcto. Advertencia real: es una demostración de curso, por lo que las convenciones están codificadas al estilo de un autor y la mitad de la prosa del cuerpo está en chino.
Probado el: 2026-07-21 · Claude Code 2.x (agent harness)
Instalación
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). Comandos y prompts de ejemplo
/api-conventionsReglas REST internas que Claude aplica al diseñar endpoints: forma de URL, data/error/meta, 422
Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards