El skill que describe PRs: convierte un diff en una descripción que el revisor sí va a leer

La mayoría de las descripciones de PR están vacías o son un copia-pega del título del commit, y quien revisa lo paga. Abre el diff en frío y va deduciendo tu intención línea por línea. El arreglo no es disciplina, que se te va a olvidar un viernes con prisa. Es un pequeño skill de Claude Code que lee el diff y redacta la descripción por ti. Aquí repaso qué hace este skill que describe PRs, el único momento en que debe dispararse, cómo funciona por dentro, una corrida real con su salida, los ajustes que vale la pena tocar y la única limitación que decide si el borrador es confiable o peligroso.

Aclaremos las expectativas de entrada: este skill no hace que tu PR sea bueno. Convierte la parte mecánica de una buena descripción, listar qué cambió y cómo probarlo, en algo que se escribe solo, para que la parte humana, el por qué del cambio, sea lo único que te quede por teclear. En ese reparto del trabajo está toda la idea.

01 · Qué hace el skill de verdad

Este skill que describe PRs es un redactor empaquetado que invocas en vez de quedarte mirando el cuadro de descripción en blanco. Lee el diff contra la rama base y produce una descripción con tres partes fijas:

1. Qué y por qué. Un párrafo apretado: qué hace el cambio, en lenguaje claro, y, hasta donde el diff lo deje ver, la razón. El "qué" se conoce por completo a partir del código. El "por qué" es donde el skill deja un hueco bien marcado para que lo llenes tú, porque no puede leer tu motivación.
2. Cómo probarlo. Pasos numerados y concretos que quien revisa pueda correr de verdad: el comando, la ruta a la que pegarle, el input que darle, el resultado que esperar. No "prueba el feature." Los pasos literales. Esta es la parte que más valoran los revisores y la que más se saltan los autores.
3. Riesgo / notas. La lista corta de cosas que conviene mirar con lupa: una migración difícil de revertir, un cambio en auth, una ruta que no pudiste probar del todo, un pendiente conocido. Aquí te ganas la confianza de quien revisa señalando tus propios puntos flacos.

La audiencia es una persona concreta: un revisor con poco tiempo. Una buena descripción es una herramienta de triaje. Le dice dónde concentrar la atención y qué puede ojear tranquilo. Por eso las tres partes van en este orden: ubicar, luego facilitar la verificación, luego marcar el peligro.

02 · Cuándo debe dispararse

Dispáralo en un solo momento: justo antes de abrir el PR, cuando la rama ya está cerrada, con los cambios confirmados y subidos y el diff contra la base ya estable. Antes de eso estás describiendo algo que todavía se mueve. La descripción queda vieja en cuanto subes otro commit.

En concreto, úsalo cuando:

• Terminaste una rama de feature o de fix y vas a correr gh pr create (o a hacer clic en "New pull request").
• Estás reabriendo o actualizando un PR a fondo y la descripción vieja ya no coincide con el diff.
• Heredaste la rama de otra persona y necesitas entender y documentar qué hace de verdad antes de mandarla a revisión.

No lo dispares para:

• Un PR en draft que abres solo para que corra el CI. Deja la descripción para cuando el cambio sea de verdad.
• Un cambio de una línea, evidente de por sí, donde el título ya lo dice todo. Una descripción de puro trámite es ruido, y los revisores terminan saltándose tus descripciones si la mitad es relleno.
• Generar el por qué desde cero. El skill lo puede armar, pero si lo dejas inventar una justificación, vas a publicar una explicación tan segura como equivocada, que despista al revisor más que no poner ninguna.

El encuadre honesto: este skill quita la fricción que te hace escribir una mala descripción (o ninguna). Lo que no quita es el pensamiento que hace que una descripción sea buena.

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 un cuerpo que le dice al modelo qué hacer. El campo description es lo que dispara el skill. Es lo que Claude lee para decidir si viene al caso, así que tiene que decir cuándo usarlo, no solo qué es.

Aquí va una definición completa y funcional:

---
name: pr-describer
description: >
  Redacta la descripción de un pull request desde el diff contra
  la rama base: qué cambió, por qué y cómo probarlo. Úsalo justo
  antes de abrir un PR, cuando el usuario diga "escribe mi
  descripción de PR", "describe este PR" o "voy a abrir un PR".
---

Estás redactando la descripción de un PR. Sigue estos pasos al pie
de la letra.

1. Determina la rama base (por defecto: main). Corre
   **git diff main...HEAD** y **git log main..HEAD --oneline**
   para ver qué cambió y la historia de commits.

2. Escribe tres secciones, con estos encabezados exactos:

   ## Qué y por qué
   Un párrafo. Di qué hace el cambio, desde el diff. Para el POR
   QUÉ, escribe lo que el diff implica y agrega una línea:
   "> TODO(autor): confirma la razón real de este cambio."
   NUNCA inventes una justificación y la presentes como un hecho.

   ## Cómo probarlo
   Pasos numerados y ejecutables que quien revisa pueda seguir:
   comandos exactos, rutas, inputs y resultados esperados.
   Dedúcelos de los archivos cambiados. Si no puedes inferir un
   paso, márcalo "> TODO(autor): agrega un paso de prueba manual."

   ## Riesgo / notas
   Bullets: migraciones, cambios de auth/seguridad, breaking
   changes, rutas que se ve que NO quedaron cubiertas por tests
   en el diff.

3. Sé conciso. NO repitas el diff entero. NO digas que el cambio
   está probado salvo que aparezcan archivos de test en el diff.

Por dentro el flujo es mecánico: cuando tu pedido coincide con la descripción, Claude carga el cuerpo del skill, corre los comandos git diff y git log contra la base, lee los hunks cambiados y los mensajes de commit, y llena las tres secciones. Los encabezados fijos y los marcadores TODO explícitos son lo que hace segura la salida. Cada lugar donde el skill está adivinando queda marcado como tal, así no puedes publicar sin querer una justificación inventada como si fuera la verdad.

Un retoque útil: que el skill lea también los mensajes de commit, no solo el diff. Los buenos títulos de commit suelen traer el "por qué" que el diff no tiene, e incorporarlos le da al borrador una buena ventaja en la única sección donde flaquea.

04 · Una corrida concreta y su salida

Terminas una rama, la subes y le pides a Claude: "Escribe mi descripción de PR." El pedido coincide, el skill corre git diff main...HEAD, lee los cambios a un flujo de checkout y te devuelve algo con esta forma:

## Qué y por qué
Agrega claves de idempotencia al endpoint de checkout para que un
pago enviado dos veces no cree dos cargos. El handler ahora guarda
una clave por request y devuelve el resultado original en el replay.

> TODO(autor): confirma la razón real — ¿salió de un incidente
> específico de cargo duplicado? Pon el link aquí.

## Cómo probarlo
1. Levanta la app: **npm run dev**.
2. Haz POST a /api/checkout con un header Idempotency-Key y un
   carrito válido. Espera 200 y un id de cargo.
3. Repite exactamente el mismo request (misma clave). Espera el
   MISMO id de cargo y NINGÚN segundo cargo en el dashboard de pagos.
4. Haz POST con una clave nueva. Espera un cargo nuevo.

## Riesgo / notas
- Agrega una migración (tabla idempotency_keys). Revertir exige
  dropear la tabla — coordina con el deploy.
- En este PR las claves se guardan sin TTL. La limpieza es un
  pendiente, no se atiende aquí.
- No hay test de carga/concurrencia en el diff; la carrera entre
  dos primeros requests simultáneos queda sin probar.

Esa es la salida que buscas. El "qué" es exacto y sale directo del código. El "por qué" está esbozado, pero marcado con honestidad como algo que solo tú puedes confirmar. Los pasos de prueba se corren tal cual están escritos. Y el bloque de riesgo saca a la luz justo las cosas en las que un revisor debería insistir, como el TTL que falta y la carrera sin probar, en vez de fingir que el cambio es infalible. Agregas una frase con el link al incidente, borras el TODO y abres el PR.

Compáralo con el modo de falla: una descripción generada que afirma con todo el aplomo "esto arregla el bug de cargo duplicado que reportó el equipo de pagos", menciona un equipo que tal vez ni existe, dice "probado a fondo" y nunca menciona la carrera sin probar. El mismo modelo, pero sin frenos, que es justo lo que los marcadores TODO y la regla de "nunca inventes una justificación" vienen a evitar.

05 · Configuración y las perillas que importan

Casi todo el ajuste vive en el cuerpo del skill, no en flags. Lo que vale la pena tocar:

• Rama base. Por defecto main, pero deja que el skill detecte la base real (algunos repos usan develop o una rama de release). Hacer diff contra la base equivocada produce una descripción de cambios que ni siquiera están en el PR.
• Forma del template. Calca exacto los encabezados del template de PR de tu equipo. Si tu repo tiene un .github/pull_request_template.md, apunta el skill a él para que la salida entre directo en vez de pelear con el formulario.
• Lectura de mensajes de commit. Dile que lea git log base..HEAD y se apoye en los títulos de commit para el "por qué". Es la forma más barata de mejorar la sección más floja.
• Disciplina de TODO. Conserva los marcadores explícitos de TODO(autor). Son parte de la función, no estorbo. Así el skill se mantiene honesto sobre la línea entre lo que sabe y lo que adivina.
• Tope de longitud. Ponle tope. Una descripción de PR más larga que el diff es mala señal. Los revisores ojean las descripciones largas y se pierden el único riesgo que de verdad importaba. Conciso y fácil de escanear le gana a completo.

El no-objetivo a propósito: no lo dejes abrir el PR por ti. El borrador es un punto de partida que editas: el link al incidente, la justificación confirmada, los TODO borrados. Un skill que redacta y además envía quita justo el paso donde agregas lo único que él no pudo: tu intención.

06 · Trampas a tener en cuenta

La limitación que lo define todo: el skill puede describir el diff, pero no la motivación que tienes en la cabeza. Si el PR arregla un bug sutil, el "por qué" importa más que el "qué", y el por qué es lo único que el modelo literalmente no puede leer del código. Trata el borrador generado como un esqueleto donde vuelcas el razonamiento, nunca como un documento terminado.

Otras que te pueden costar caro:

• Justificación inventada. Si no lo restringes, el modelo va a fabricar una razón que suena plausible y la va a afirmar como un hecho. Eso es peor que el silencio. Un "por qué" equivocado y dicho con seguridad manda al revisor por el camino errado. La regla del marcador TODO existe justo para que el modelo no afirme cosas que en realidad está adivinando.
• Falsa confianza en los tests. Solo ve archivos de test si están en el diff, y aun así no los puede correr. Nunca debe decir que el cambio está probado solo con la fuerza del código. Si solo corriste el camino feliz, la descripción debe decirlo. El caso límite sin probar es justo lo que el revisor está ahí para cazar.
• Rama base equivocada. Haz diff contra la base errada y la descripción entera habla del conjunto de cambios equivocado, y a menudo sin avisar, porque igual produce una prosa que suena fluida. Confirma la base cada vez, o haz que el skill imprima qué base usó para que un desajuste salte a la vista.
• Desactualizada tras un force-push. Reescribe la historia o sube más commits y la descripción deja de coincidir con el diff. Regenérala después del push final, no antes. Y si una ronda de revisión agrega commits, actualiza los pasos de "Cómo probarlo" para que cuadren.
• Puntos ciegos de seguridad. Un redactor que solo ve el diff no puede razonar sobre una vulnerabilidad repartida en archivos que no leyó. Para cualquier cosa que toque auth o secretos, el bloque de riesgo es un llamado a tu criterio, no un visto bueno. (En Infuse, el gestor de secretos que construyo, la descripción del PR jamás sustituye una revisión real del código que maneja llaves.)

Un buen skill que describe PRs no va a hacer que tu cambio sea correcto, pero sí te quita de en medio el andamiaje aburrido para que lo único que quede por escribir sea la parte que necesita a un humano: por qué existe esto y dónde podría salir mal. Móntalo una vez, mantén honestos los marcadores TODO y trata el borrador como un primer esqueleto bien armado que tú terminas, no como una descripción que publicas sin leer. Quien revisa al otro lado va a notar la diferencia la primera vez que abra un PR y ya sepa exactamente dónde mirar.