El skill de revisión de código: un revisor que lee el diff, no el repo

En cada commit quieres lo mismo: un segundo par de ojos rápido que atrape el off-by-one antes de que salga, sin darte una charla sobre el estilo de las llaves que el linter ya resuelve. Pegar "revisa este diff, marca primero los bugs, ignora el estilo" en el chat cada vez funciona, hasta que se te olvida una cláusula y la revisión empieza a desviarse. Un skill de revisión de código deja fijo ese set de instrucciones en algo que invocas por nombre, así el criterio nunca cambia y la revisión casi no cuesta nada. Aquí te cuento qué hace el skill, cuándo exactamente debe activarse, cómo funciona por dentro, una invocación real con su salida, los ajustes de configuración y las trampas que deciden si terminas confiando en él.

Lo primero que conviene grabarse: un skill no es un revisor más inteligente, es uno consistente. La inteligencia es el mismo modelo con el que hablarías de todos modos. Lo que ganas con el skill es que el mismo checklist, en el mismo orden, con las mismas restricciones estrictas, corre cada vez, y esa consistencia es lo que hace que valga la pena leer la salida en lugar de ponerte a discutirla.

01 · Qué hace el skill en realidad

Un skill de revisión de código es un revisor empaquetado que llamas cuando lo necesitas, en lugar de volver a escribir las instrucciones. Quítale el empaque y hace tres cosas, en este orden:

1. Resume el cambio. Una o dos frases sobre lo que el diff hace de verdad, no lo que dice el mensaje del commit, sino lo que hace el código. Es el chequeo de cordura barato: si el resumen no coincide con tu intención, ya encontraste un problema.
2. Lista los riesgos de corrección. Los bugs que importan: errores off-by-one, manejo de null y undefined, rutas de error sin atender, condiciones de carrera, fugas de recursos, un chequeo que quedó muerto porque se movió un return temprano. Cada uno lleva su archivo:línea para que saltes directo.
3. Lista las limpiezas opcionales, aparte. Duplicación que podrías extraer, un nombre más claro, una rama más simple. Van en su propio bloque para que las ojees o las saltes sin que los bugs reales se pierdan en el ruido.

La separación entre los bloques 2 y 3 es el corazón del diseño. Mezclados, un bug real de null-deref se ahoga bajo seis sugerencias de "considera renombrar esta variable" y dejas de leer. Separados, lees el bloque de corrección con calma y tomas el de calidad como un menú: agarras lo que quieras.

02 · Cuándo debe activarse

Actívalo en un solo momento: después de poner un cambio en stage y antes de hacer commit o abrir el PR. Esa es la ventana donde rinde, porque el diff es chico, la intención todavía está fresca en tu cabeza y actuar sobre un hallazgo sale barato, solo editas y vuelves a hacer stage.

En concreto, úsalo cuando:

• Estás por hacer git commit y quieres una pasada de cordura sobre los hunks en stage.
• Terminaste una rama de una funcionalidad y vas a abrir un PR, revisa tu propio diff antes de que alguien gaste su tiempo en él.
• Tocaste algo delicado (auth, dinero, una migración) y quieres un segundo vistazo ordenado antes de que eso siga su camino.

No lo uses para:

• Una auditoría del repo completo. Ese es otro trabajo, con otro perfil de costo, mejor apunta un skill de seguridad o de arquitectura al codebase.
• Puro formateo o ruido de lint. De eso ya se encarga el linter; correr una revisión sobre un diff de Prettier es desperdicio puro.
• Archivos generados, lockfiles o código de terceros. Dile al skill que se salte esas rutas para que no queme tokens revisando salida de máquina.

Seamos honestos: esta es una primera pasada, no la única. Atrapa los errores aburridos y comunes que nunca deberían llegar a un revisor humano. No reemplaza a la persona que de verdad entiende por qué existe el cambio.

03 · Cómo funciona por dentro

Un skill de Claude Code es un directorio con un archivo markdown, un frontmatter (un nombre y una descripción) más el cuerpo que le dice al modelo qué hacer. La descripción es lo que dispara el skill: es lo que Claude lee para decidir si encaja con tu pedido, así que tiene que dejar claro cuándo usarlo, no solo qué es.

Aquí tienes una definición completa y funcional:

---
name: code-review
description: >
  Revisa el diff actual en stage buscando bugs de corrección y
  limpiezas opcionales. Úsalo justo antes de un commit o al abrir
  un PR, cuando el usuario pida "revisa mis cambios" o "revisa este diff".
---

Estás revisando un diff en STAGE. Sigue estos pasos al pie de la letra.

1. Corre **git diff --staged** y lee solo los hunks cambiados más el
   contexto mínimo alrededor. Salta lockfiles, archivos generados y
   cualquier cosa bajo vendor o node_modules.

2. Escribe un RESUMEN: 1-2 frases de lo que hace el cambio.

3. Escribe CORRECCIÓN primero. Lista solo bugs reales: off-by-one,
   manejo de null/undefined, errores sin atender, condiciones de
   carrera, fugas de recursos, lógica rota. Da **archivo:línea** en
   cada uno. Si no encuentras ninguno, di "Sin problemas de corrección".

4. Escribe CALIDAD después, en un bloque aparte: duplicación,
   nombres, estructura más simple. Son opcionales.

5. Califica contra el DIFF, no contra el código perfecto. NO reescribas
   funciones enteras. NO comentes el formateo que impone el linter.
   NO inventes problemas para parecer minucioso.

Por dentro el flujo es mecánico: cuando tu pedido coincide con la descripción, Claude carga el cuerpo del skill en contexto, corre el comando git diff --staged, lee los hunks que devuelve y arma una salida con la forma de los pasos numerados. Como el cuerpo fija el orden y las restricciones, dos corridas sobre el mismo diff terminan más o menos en el mismo lugar. El modelo sigue poniendo el razonamiento; el skill solo se asegura de que razone sobre lo correcto y en el orden correcto.

Un buen ajuste extra es que pida git diff (sin stage) o git diff main...HEAD (la rama completa) cuando ese sea el mejor objetivo, pero que por defecto vaya al stage, porque ahí es donde de verdad ocurren la mayoría de las revisiones.

04 · Una invocación concreta y su salida

Pones un cambio chico en stage y le pides a Claude: "Revisa mis cambios en stage." La descripción coincide, el skill corre y recibes algo con esta forma:

RESUMEN
Agrega un wrapper de reintentos alrededor de la llamada a la API
de pagos en checkout.ts, con un loop fijo de 3 intentos.

CORRECCIÓN
- checkout.ts:42 - El loop reintenta ante CUALQUIER error lanzado,
  incluido un error de validación 400 que nunca va a tener éxito.
  Reintentar un error no reintentable gasta 3 viajes y atrasa la
  falla que ve el usuario. Reintenta solo en 5xx/red.
- checkout.ts:48 - Sin espera entre intentos. Tres reintentos
  inmediatos pueden machacar un endpoint que ya viene mal. Agrega
  backoff.

CALIDAD
- checkout.ts:39 - El número mágico 3 podría ser una const con
  nombre MAX_RETRIES para más claridad. Opcional.

Esa es la salida que quieres. Dos bugs reales que sí querrías arreglar antes del merge, cada uno con número de línea y un por qué de una sola frase, y después una única limpieza de tómala o déjala. Ninguna función reescrita, ningún párrafo sobre indentación, ningún relleno para parecer minucioso. Arreglas los dos puntos de corrección, vuelves a hacer stage y publicas.

Compáralo con el modo de falla: una respuesta de 200 líneas que reescribe el helper de reintentos completo "para que quede más limpio", reordena los imports y entierra el bug real de "reintenta en 400" en algún lugar del cuarto párrafo. Mismo modelo, pero sin frenos. Es justo lo que las restricciones del skill están para evitar.

05 · Configuración y los ajustes que importan

Casi toda la configuración vive en el cuerpo del skill, no en flags. Los ajustes que vale la pena tocar:

• Objetivo del diff. Por defecto git diff --staged. Deja que se pueda cambiar al diff de la rama completa (git diff main...HEAD) para una pasada antes del merge, o al diff sin stage para revisar trabajo en curso.
• Rutas excluidas. Sáltate explícitamente lockfiles, código generado, snapshots y directorios de terceros. Es la palanca que más mueve la relación señal-ruido.
• Etiquetas de severidad. Que marque los hallazgos (por ejemplo bloqueante vs detalle) para que filtres de un vistazo. Mantén la escala chica, dos o tres niveles, no siete.
• Reglas del proyecto. Trae las convenciones de revisión que ya tengas en un CLAUDE.md o un archivo de reglas (estilo de commit, patrones prohibidos, chequeos de seguridad obligatorios) para que el skill respete los estándares de la casa en lugar de inventar los suyos.
• Tope de alcance. Para un diff enorme, que revise primero los archivos de mayor riesgo y lo diga, en vez de pasar por encima de todo de forma superficial. Una revisión enfocada en el 20% peligroso vale más que una capa fina sobre el 100%.

El límite que pones a propósito: no dejes que aplique los fixes por su cuenta. Un revisor que edita deja de ser revisor. Pasa a ser un segundo autor cuyo trabajo nadie revisó. Mantenlo de solo lectura. Tú lees el hallazgo, tú haces el cambio. (Si sí quieres que aplique con confirmación, eso es un skill aparte y bien etiquetado, con un paso de confirmación humana, no un default silencioso.)

06 · Trampas a evitar

La línea que lo decide todo es evalúa contra el diff, no contra tu idea de código perfecto. Sin ella, el skill cae en "así lo habría escrito yo todo", y el único bug real se ahoga en una reescritura que nadie pidió. Pon esa restricción en el cuerpo tal cual y le cambia el carácter por completo a la salida.

Otras que te pueden morder:

• Falsa minuciosidad. Si lo dejas solo, el modelo inventa hallazgos al filo para parecer aplicado. Dile sin rodeos que "sin problemas de corrección" es una respuesta válida y buena. Un diff limpio debe dar una revisión corta, no una lista inflada.
• Ceguera de contexto. Solo ve el diff, así que puede marcar como "faltante" un chequeo de null que en realidad ya garantiza un caller que él no ve. Toma los hallazgos de corrección como preguntas para verificar, no como veredictos. El skill se equivoca a veces; tú eres quien conoce el código de alrededor.
• Exceso de confianza en seguridad. Un revisor con alcance de diff no es una auditoría de seguridad, no puede razonar sobre una vulnerabilidad que se reparte entre archivos que no leyó. Para auth, cripto o cualquier cosa que maneje secretos, esto es un primer filtro, no la última palabra. (En Infuse, el gestor de secretos que construyo, nunca dejo que una revisión de diff sea el último chequeo de nada que toque el manejo de llaves.)
• Deriva del prompt viejo. A medida que tu codebase evoluciona, un prompt de revisión viejo te fastidia con patrones que ya dejaste atrás. Versiona el skill, hazle smoke test contra tus fixtures de diffs rotos y actualízalo como cualquier otra pieza de código.

Un buen skill de revisión de código no te va a convertir en mejor ingeniero, pero sí evita que los errores tontos y repetitivos lleguen a la mesa de un revisor humano, lo que libera a esa persona para concentrar su atención en lo que solo un humano puede juzgar. Constrúyelo una vez, ponle restricciones firmes y trata su salida como una primera opinión afilada, no como un veredicto. El día que te diga "sin problemas de corrección" sobre un diff limpio y lo diga en serio, vas a saber que las restricciones están haciendo su trabajo.