El skill de mensajes de commit: escribe el porqué, no el diff

Dentro de seis meses, alguien corre git blame sobre una línea que no tiene sentido, cae en tu commit y lee "update auth logic". Eso no le dice nada. El historial de cambios es la única documentación que siempre está ahí y casi siempre resulta inútil, porque escribir un buen mensaje al hacer commit es aburrido y tú ya tienes la cabeza en la siguiente tarea. Un skill de mensajes de commit arregla el incentivo. Lee el diff que tienes en stage y redacta un commit convencional cuyo asunto se lee de una vez y cuyo cuerpo explica el porqué, así quien lo lea más adelante recibe el contexto que, si no, se pierde en un hilo de Slack. Aquí repaso qué hace el skill, cuándo debe activarse, cómo funciona por dentro, una corrida real con su salida, la config que importa y los detalles que separan un log útil del ruido.

Algo que conviene dejar claro de entrada. El skill no escribe mejor que tú. Escribe más parejo que tú. El mismo formato y la misma instrucción de "explica la intención" se aplican en cada commit, hasta en los que normalmente harías a la carrera. Y un log donde cada entrada tiene la misma forma es un log que de verdad puedes leer.

01 · Qué hace el skill realmente

Un skill de mensajes de commit es un escritor empaquetado que invocas a la hora del commit en vez de volver a teclear las mismas instrucciones. Quítale el empaque y hace tres cosas:

1. Leer el cambio en stage. Corre git diff --staged y lee los hunks más el contexto suficiente para entender el cambio como una unidad. No archivo por archivo, sino como una sola edición lógica con una intención detrás.
2. Escribir un asunto convencional. Una línea con tipo y scope opcional dentro del límite de largo: fix(auth): rechaza tokens emitidos antes del reset. En imperativo, sin punto final, con el tipo elegido según el cambio (fix, feat, refactor, docs, test, chore).
3. Escribir un cuerpo que explique el porqué. Prosa con saltos de línea bajo el asunto que recoge el razonamiento: qué estaba mal, qué hace el cambio al respecto y cualquier concesión que valga la pena dejar anotada. El cuerpo es opcional en cambios triviales y es la razón de ser del ejercicio en todo lo demás.

El formato de commit convencional no es adorno. El prefijo de tipo permite que los generadores de changelog agrupen, y el scope le dice a quien lee qué subsistema se tocó. Pero el formato es la parte fácil. Eso te lo da cualquier plantilla. La parte difícil y valiosa es el cuerpo, y ahí es donde fallan la mayoría de los mensajes de commit.

02 · Cuándo debe activarse

Actívalo en un solo momento: después de poner un cambio en stage y justo antes de hacer commit. Esa ventana es donde rinde, porque el diff ya está listo, tu intención sigue fresca y el costo de un buen mensaje es casi cero. De todos modos ya estás detenido en el paso del commit.

En concreto, úsalo cuando:

• Pusiste en stage un cambio real y vas a hacer git commit. Deja que el skill redacte el mensaje para que estés editando prosa, no mirando un editor en blanco.
• Estás haciendo squash de una rama desordenada en un solo commit limpio y necesitas un asunto y un cuerpo que describan el conjunto, no el último fixup.
• Tocaste algo delicado (auth, una migración, manejo de dinero) donde el porqué de verdad le importa a quien lo lea después.

No lo actives para:

• Un commit donde el mensaje de verdad es trivial, como subir una versión o arreglar un typo obvio. chore: sube la versión a 1.4.2 no necesita un cuerpo generado, y forzar uno solo produce relleno.
• Un diff que mezcla dos cambios sin relación. El skill, obediente, escribirá un asunto que abarque los dos, que es justo el resultado equivocado. Lo correcto es dividir antes el cambio en stage en dos commits. Un skill de mensajes de commit no sustituye la disciplina al armar el stage.
• Un diff vacío o de solo espacios en blanco. No hay nada que explicar.

El encuadre honesto: el skill redacta, tú decides. Es un punto de partida, no una autoridad sobre lo que significa tu cambio. Cuando adivine mal tu intención, y en un cambio no obvio a veces lo hará, tú eres quien lo arregla antes de hacer commit.

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. La descripción es lo que decide si se activa. Es lo que Claude lee para decidir si el skill viene al caso, así que tiene que decir con claridad cuándo usarlo, no solo qué es.

Aquí va una definición completa y funcional:

---
name: commit-message
description: >
  Escribe un mensaje de commit convencional desde el diff en stage.
  Úsalo justo antes de hacer commit, cuando el usuario pida "escribe
  el mensaje de commit", "redacta el commit" o "haz commit de esto".
  Devuelve solo el mensaje; el commit lo corre el usuario.
---

Estás escribiendo un mensaje de commit para un diff en STAGE. Sigue
estos pasos al pie de la letra.

1. Corre **git diff --staged** y lee el cambio como una unidad
   lógica. Si el diff en stage mezcla dos cambios sin relación,
   dilo y sugiere dividirlo en vez de escribir un solo mensaje.

2. ASUNTO: una línea convencional, en imperativo, sin punto final,
   bajo 72 chars: type(scope): resumen. Elige el tipo según el
   cambio (fix, feat, refactor, docs, test, chore).

3. CUERPO (sáltalo en cambios triviales): con saltos cada ~72
   chars. Explica el PORQUÉ del cambio: el problema y el
   razonamiento. NO repitas el diff. "Cambié la función de auth"
   está prohibido; el diff ya muestra eso.

4. Devuelve el mensaje en un bloque cercado SOLAMENTE. No corras
   git commit. El commit lo hace el usuario.

Por dentro, el flujo es mecánico. Cuando tu pedido coincide con la descripción, Claude carga el cuerpo del skill en contexto, corre git diff --staged, lee los hunks y produce un mensaje con la forma de los pasos numerados. Como el cuerpo fija el formato y las restricciones, dos corridas sobre el mismo diff terminan más o menos igual. El modelo sigue haciendo la escritura. El skill se asegura de que escriba lo correcto y con la forma correcta cada vez.

Un refinamiento útil: haz que el skill tome la convención de commits que ya tengas en un CLAUDE.md o un archivo de reglas, así se ajusta a tu lista de tipos y a tu límite de largo de asunto en vez de inventar los suyos. Casi todos los equipos ya tienen alguna convención escrita en algún lado. Apunta el skill hacia ella.

04 · Una corrida concreta y su salida

Pones un fix en stage y le pides a Claude: "Escribe el mensaje de commit." La descripción coincide, el skill corre git diff --staged y te devuelve algo así:

fix(auth): rechaza tokens emitidos antes del reset de contraseña

Los tokens creados antes de un reset de contraseña seguían válidos
después, así que un token robado sobrevivía al mismo reset que
debía revocarlo. Compara el issued-at de cada token contra el
timestamp del último reset de la cuenta y rechaza lo más viejo.

El chequeo vive en el camino de verify para que cubra también el
refresh, no solo el login inicial.

Esa es la salida que quieres. El asunto se lee de una vez en git log --oneline y le dice a quien lo lee el tipo, el scope y la idea general. El cuerpo responde la pregunta que git blame terminará haciendo tarde o temprano, ¿por qué está esto aquí?, con el razonamiento real de seguridad, más una nota sobre la concesión de dónde vive el chequeo. Nadie que lea esto en seis meses tendrá que reconstruir el razonamiento a partir del diff.

Compáralo con el modo de falla que el skill existe para evitar:

update auth

cambié la función validateToken para agregar un chequeo nuevo en
el campo issued-at y actualicé los tests

Mismo diff, sin skill. El asunto no tiene tipo y es vago, y el cuerpo solo narra lo que el diff ya muestra. Repite el qué y nunca toca el porqué. Quien lo lea todavía tiene que abrir el diff y deducir el razonamiento a la inversa. Esa es la diferencia que hace un skill con restricciones: obliga al cuerpo a cargar la intención en vez de repetir el cambio.

05 · Configuración y las perillas que importan

Casi todo el ajuste vive en el cuerpo del skill, no en flags. Las perillas que vale la pena configurar:

• Fuente de la convención. Apunta el skill a tu convención de commits ya existente (la lista de tipos, el vocabulario de scopes, el tope de largo del asunto) en vez de dejar que use una genérica. La consistencia con el historial de tu repo importa más que cualquier estilo en particular.
• Largo del asunto. Define el tope duro. 50 o 72 chars son los comunes. Que el skill lo haga cumplir. Un asunto que se corta en git log --oneline echa a perder el formato.
• Umbral del cuerpo. Dile cuándo saltarse el cuerpo. Un typo de una línea o subir la versión no debería llevar un párrafo fabricado. Un cambio de lógica no obvio siempre debería llevar uno.
• Soporte de footers. Si tu flujo usa trailers (referencias a issues, líneas de co-autor, marcadores de breaking change), decláralos para que el skill los ponga en el lugar correcto en vez de meterlos a la fuerza en el cuerpo.
• Alcance del diff. Por defecto, el stage. Permite apuntar a git diff (sin stage) o a un rango cuando estés redactando un mensaje para un squash, pero deja el stage como default porque ahí es donde de verdad pasan los commits.

El no-objetivo, a propósito: el skill escribe el mensaje, no hace el commit. Mantenlo solo de salida. Lees el borrador, arreglas cualquier cosa que haya malinterpretado de tu intención y corres git commit tú mismo. Un skill que hace el commit solo elimina el único chequeo humano que atrapa un mensaje con intención equivocada antes de que quede fijo en el historial. Y el historial es lo único que no puedes corregir después sin que se note.

06 · Cuidados

La línea que decide todo es explica el porqué, no el qué. Sin ella, el skill cae en narrar el diff en prosa, como "cambié la función para agregar un chequeo", que no vale nada porque el diff ya muestra eso. Pon la prohibición de repetir el diff en el cuerpo tal cual y le cambia el carácter a cada mensaje que el skill escribe.

Otros que muerden:

• La trampa del commit mezclado. Si pones en stage un feature y un bug fix sin relación juntos, el skill escribirá un asunto que, con toda honestidad, abarca los dos, y eso en sí es la señal de alarma. Un asunto que necesita una "y" casi siempre son dos commits. Haz que el skill marque la mezcla y sugiera dividir en vez de taparla con un resumen vago. Un historial limpio vale el minuto extra al armar el stage.
• Intención inventada. El skill solo ve el diff, así que puede adivinar por qué hiciste un cambio y adivinar mal, como atribuir un refactor a un motivo de rendimiento cuando lo hiciste por legibilidad. Trata el cuerpo como un borrador de tu razonamiento, no como una transcripción. Tú eres quien sabe por qué. El skill solo te ahorra el tecleo.
• Cuerpos demasiado entusiastas. Sin restricción, escribe un párrafo para arreglar un typo de una línea. Dale un umbral explícito para saltarse el cuerpo, o tu log se llena de ceremonia alrededor de cambios triviales y las explicaciones reales se pierden en el ruido.
• Deriva de la convención. Los defaults genéricos producen commits que no encajan con el historial existente de tu repo, con otra lista de tipos u otro estilo de scope. Aliméntalo con tu convención real y versiona el skill junto a ella, para que los mensajes que escribe parezcan que pertenecen ahí.

Un skill de mensajes de commit no va a hacer mejores tus cambios, pero sí va a hacer que su historial valga la pena leerse. Y en ese historial es donde se apoya un compañero, o tu yo del futuro, cuando algo se rompe y la única pista es una línea de git blame. Constrúyelo una vez, restríngelo para que explique la intención y quédate tú entre el borrador y el commit. El día que un compañero lea uno de tus mensajes y entienda el cambio sin abrir el diff, el skill habrá hecho su trabajo.