La skill de Claude que audita su propio spec OpenAPI

Le pides a Claude que diseñe una API y obtienes algo que parece correcto: sustantivos en plural, un parámetro de paginación, un prefijo de versión. Luego lees con atención y un endpoint usa page_size donde el resto de listados usan limit, un error de validación está documentado como 500, y el spec incluye un nullable: true que no existe en OpenAPI 3.1. Cada error es pequeño. Juntos marcan la diferencia entre una API que funciona y una API que se mantiene consistente al cambiar — y nada en un prompt de "aquí tienes los principios" fuerza lo segundo.

El resultado es api-discipline, y la clave no es que conozca las convenciones REST — eso lo hace cualquier skill de este nicho. La clave es que comprueba su propia salida antes de entregarla: OpenAPI 3.1 limpio según el validador, una pasada obligatoria de consistencia entre endpoints, y un diff de cambios de ruptura en cada edición. Es gratis y tiene licencia MIT: github.com/Skillproofdev/api-discipline.

La brecha: todos enseñan los principios, nadie los exige

Antes de escribir una sola línea, revisamos 84 skills de diseño de API y OpenAPI en nuestro índice de 16.682 skills más el ecosistema web independiente. El patrón es constante. El repo más grande (37.6k estrellas) es un manual de conceptos con exigencia cero. El mejor construido (10.5k estrellas) nombra un linter y se queda ahí.

Y eso importa para lo que podíamos afirmar honestamente. Una salida limpia según el validador ya es, de por sí, un espacio resuelto y competitivo — la skill de 10.5k estrellas te lleva ahí. Publicar "nosotros también corremos un linter" habría sido ruido. Así que buscamos lo que nadie exige, y encontramos cuatro cosas que no existían en ninguna de las 84:

1. Una auditoría de consistencia entre endpoints como pasada obligatoria. Diez comprobaciones definidas — capitalización, pluralización, un esquema de error compartido, parámetros de paginación idénticos, formatos uniformes de id/timestamp, patrón de operationId, mismo-código-de-estado-para-la-misma-acción — se ejecutan en cada endpoint antes de entregar. Cada competidor tiene, como mucho, una viñeta de "sé consistente".
2. Disciplina de cambios de ruptura que se activa en cada edición. Cada edición del spec recibe una pasada enumerada de cambios de ruptura, respaldada mecánicamente por oasdiff breaking cuando está disponible. La herramienta ya es madura; ninguna skill revisada la integra.
3. Semántica HTTP como reglas, no como trivia. PUT reemplaza, PATCH aplica parciales, POST crea con 201 + Location, DELETE devuelve 204 — exigido con una tabla de códigos de estado, no listado como "conceptos que conviene saber".
4. Un contrato de salida para revisar/extender. "Revisa este spec" devuelve hallazgos ligados al checklist con ubicaciones y arreglos; "añade un endpoint" devuelve un diff que hereda las convenciones del spec existente más un bloque de cambios de ruptura. Los competidores solo definen la salida para diseño desde cero.

Ese es el terreno sin competencia: no la validación, sino la auditoría que corre después de la validación, más un benchmark publicado que la respalde.

El benchmark: medido, con las derrotas incluidas

Siete tareas — dos diseños desde cero, dos extensiones de spec, dos revisiones de specs con fallos con 22 violaciones sembradas entre ambas, una pregunta de convenciones. Cada una se ejecutó dos veces: un agente Claude Sonnet a pelo, otro leyendo el SKILL.md primero, prompts idénticos. Los specs se puntuaron mecánicamente con redocly lint y spectral lint, las ediciones se compararon con oasdiff breaking, y las capturas de violaciones sembradas las juzgaron agentes verificadores independientes.

Métrica (menor es mejor)	base	skill
Errores de validador, diseño desde cero (redocly)	18	0
Violaciones de consistencia, las 4 tareas de diseño	6	0
Errores de semántica HTTP, las 4 tareas de diseño	3	0
Violaciones sembradas detectadas, revisión T6 (mayor es mejor)	10/10	9/10

Medido el 2026-07-10 con Redocly CLI 2.38.0, Spectral 6.16.1 y oasdiff 1.23.0. El detalle completo por hallazgo está en bench/results/verdict.md.

La brecha de validador es una historia clara: las dos ejecuciones a pelo emitieron nullable: true de OpenAPI 3.0 en documentos declarados como openapi: 3.1.0 — un error estructural en 3.1, que usa type: [x, 'null']. Doce ocurrencias en la primera tarea desde cero, seis en la segunda. La ejecución con la skill usó la forma de 3.1 en todo momento y validó limpio. Las victorias de consistencia y semántica tienen la misma forma: las ejecuciones a pelo publicaron endpoints con verbo en la ruta (/tasks/{id}/complete), un segundo esquema de error improvisado junto al compartido, y un create que devolvía 200 en vez de 201. La ejecución con la skill modeló las acciones como sub-recursos con sustantivo y reutilizó un único esquema de error en todas partes — 0 en las cuatro tareas de diseño.

Dónde perdió la skill — y un resultado del que no nos atribuimos el mérito

Dos notas honestas, porque nuestra metodología exige mostrar las derrotas junto a las victorias.

La skill perdió en T6 por una violación sembrada. En la revisión cargada de semántica, la pasada de forma libre del agente a pelo recorrió cada operación de manera exhaustiva y captó un 201 Created en POST /articles sin cabecera Location. La revisión del agente con la skill, organizada en torno al checklist de consistencia, marcó los cuatro defectos de método HTTP y las cinco semillas de consistencia pero no revisó cada 201 en busca de su Location — 9/10 frente a 10/10. La revisión estructurada cubrió menos de lo que captó una lectura exhaustiva. Eso ya está arreglado en el checklist con una línea explícita de "cada 201 tiene Location".

Un resultado de cambios de ruptura queda excluido del titular. En la tarea de extensión del spec, el agente con la skill reportó que había visto una pista de ground truth filtrada en el archivo de la tarea ("ambos cambios son de ruptura") antes de analizar — un desliz de protocolo, ya que el brazo con la skill debería leer solo el SKILL.md. Así que ese resultado no se reclama como una victoria independiente, aunque se vea bien sobre el papel. Dos cosas hacen que el hallazgo de fondo sea sólido de todas formas: el brazo a pelo, que nunca lee el archivo de la tarea, concluyó de forma independiente que ambos cambios eran de ruptura; y oasdiff confirmó mecánicamente la superficie de ruptura sin importar lo que creyera cada agente. Las afirmaciones del titular se apoyan en validación, consistencia y semántica — nada de lo cual toca la filtración.

Instalación

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

Reinicia Claude Code. Se activa con "diseña una API," "añade/extiende un endpoint," "revisa este spec OpenAPI," y preguntas de convenciones REST — y se mantiene al margen del trabajo puramente GraphQL, la generación de código de SDK cliente, y las pruebas de seguridad de API. Se suma a token-discipline, que recorta lo que cuesta un trabajo de varios pasos, y research-discipline, que recorta lo que la investigación se equivoca — esta recorta hacia dónde derivan tus contratos de API.

Preguntas frecuentes

Una skill de 10.5k estrellas ya produce OpenAPI válido. ¿Por qué esta? Porque válido no es lo mismo que consistente. Un linter capta un $ref roto; no capta que un endpoint pagine con page_size mientras el resto usa limit, o que un create devuelva 200. Esa auditoría de consistencia entre endpoints es el terreno sin competencia — es lo que las skills populares no exigen, y es donde las ejecuciones a pelo acumularon 6 violaciones frente a las 0 de la skill.

¿Gestiona ediciones a un spec existente, no solo el diseño desde cero? Sí, y las trata de forma distinta. Los endpoints nuevos añadidos a un spec existente heredan sus convenciones aunque entren en conflicto con las preferencias por defecto de la skill — la consistencia con el contrato del que dependen otras personas gana a las preferencias de la skill. Cada edición también recibe una pasada enumerada de cambios de ruptura, respaldada por oasdiff breaking cuando la herramienta está disponible.

¿Necesita tener instalado oasdiff o un validador para funcionar? No. Cuando redocly/spectral u oasdiff pueden ejecutarse, los usa y reporta el comando y el resultado. Cuando no pueden, lo dice explícitamente y ejecuta una alternativa de autocomprobación definida — todos los $ref se resuelven, operationId únicos, cada parámetro de ruta declarado, cada respuesta con descripción. Nunca se salta la comprobación en silencio.

¿Es reproducible el benchmark? Sí. Siete tareas, dos brazos, puntuación mecánica donde es posible, y el ground truth preregistrado está incluido en el repo bajo bench/ground-truth/. El método completo, el detalle por hallazgo, y la nota a pie sobre la derrota en T6 y la integridad en T4 están todos en bench/results/verdict.md — no se oculta nada.