Leí el código de las skills de Matt: cuatro reglas para escribir buenas skills (y lo pillé borrando caveman)

Resumen en 30 segundos

Una buena skill persigue un solo objetivo: predictibilidad (predictability) — ante la misma situación, la IA recorre siempre el mismo proceso. Las cuatro reglas existen para eso, y cada una lleva su contraejemplo:

Cómo se dispara: o el modelo decide solo que toca usarla (y para eso ocupa contexto a perpetuidad), o solo se enciende cuando tú la llamas por su nombre. Elegir mal = contexto ocupado para nada.

Cuánto metes: en el SKILL.md solo lo que vale para todos los caminos; el resto, hundido en un archivo externo. Contraejemplos: sprawl (desparrame), sediment (sedimento).

Qué palabras usas: tira de conceptos que la IA ya trae aprendidos como leading word (palabra que tira del resto), una palabra ancla todo un bloque de comportamiento. Contraejemplos: no-op (palabra que no hace nada), duplication (duplicación).

Cómo cierra: cada paso, un completion criterion (criterio de finalización) verificable. Contraejemplo: cierra antes de terminar.

Las cuatro salen del writing-great-skills de Matt Pocock; los cuatro contraejemplos, de su propio historial de versiones. Casos reales.

Me leí el código fuente de las skills de Matt

Le das al / igual y unas skills terminan el trabajo cada vez, otras van a ratos. La diferencia no es suerte, es cómo están escritas.

Nadie tiene tiempo de leerse ese código; lo hice por ti. Mi sujeto fue Matt Pocock, el tipo que montó toda una colección de skills de colaboración con IA. Entre ellas hay una cosa preciosa: una skill que enseña a escribir buenas skills (writing-great-skills). Me empapé de ese texto, más el código y el historial de commits de decenas de sus skills, y saqué cuatro reglas.

Cuatro nada más, pero cada una con su contraejemplo — y ninguno inventado: todos salen de los commits del propio Matt, errores que cometió con sus manos y arregló con sus manos. Si hasta él tuvo que volver atrás a corregirlos, es que la mina es de verdad.

Apréndelas y pisarás menos minas escribiendo skills; y si no escribes ninguna, te llevas igual su manera de exprimir determinismo de una IA aleatoria.

Una buena skill tiene un solo criterio: predictibilidad

El modelo es estocástico — pregúntale lo mismo dos veces y puede responderte distinto. La razón de ser de una skill es sacar determinismo de esa máquina aleatoria: que recorra el mismo proceso cada vez.

«A skill exists to wrangle determinism out of a stochastic system.» — Matt, writing-great-skills

Ojo: el proceso, no la salida. Una lluvia de ideas debe escupir ideas distintas cada vez, pero la manera de desplegarse tiene que ser estable.

Para juzgar si una skill es buena hay un único criterio: predictibilidad (predictability). Las cuatro reglas de abajo sirven todas a eso.

Regla 1 · Cómo se dispara: ¿la llamas tú, o la decide el modelo?

La primera decisión al escribir una skill: ¿la usa el modelo cuando él juzga que toca, o solo se enciende cuando tú la llamas por su nombre? Técnicamente es un único interruptor — escribir o no la description:

Disparada por el modelo (model-invoked, con description): la IA la ve, la IA decide cuándo usarla. El precio: esa description cuelga del contexto en cada turno de la conversación, gastando token y atención — eso es carga de contexto.
Disparada por el usuario (user-invoked, con disable-model-invocation): se le quita la description, el modelo no la ve, solo arranca si tú tecleas su nombre. No le cuesta ni un token de contexto a la IA, pero el precio se te traslada a ti: tienes que acordarte de que existe — eso es carga cognitiva.

El principio: deja que se dispare sola únicamente cuando el modelo (u otra skill) tenga que alcanzarla por su cuenta; si no, ponla manual y te llevas gratis cero carga de contexto.

Contraejemplo: una skill que en realidad solo vas a teclear tú a mano, pero que conserva la description y ocupa tu contexto turno tras turno para nada.

Caso real: este equilibrio Matt lo pesó él mismo, ida y vuelta. El interruptor disable-model-invocation de grill-with-docs primero lo borró — dejando que el modelo la disparara solo; en la última versión lo volvió a meter, otra vez manual. El mismo interruptor, borrado y repuesto. Eso te dice que «automática o manual» es una decisión que de verdad hay que sopesar, no algo que se pone al tuntún.

Cómo lo usas: por defecto, manual — te ahorras el contexto primero; solo cuando de verdad necesites que el modelo juzgue solo «ahora toca usarla», le das description. Autocomprobación de una frase: «esta skill, ¿quién necesita alcanzarla?». Si la respuesta es «solo yo», manual.

Acumulas demasiadas skills manuales y dejas de acordarte de ellas: ahí te ha reventado la carga cognitiva. La salida es escribir otra skill enrutadora: una skill manual que lista las demás y te dice cuándo usar cuál. El ask-matt de Matt hace justo eso.

Regla 2 · Cuánto metes: en el SKILL.md solo «lo que vale para todos los caminos»

Escalera de información: lo que sirve en todos los caminos de uso va en el cuerpo del SKILL.md; lo que solo se usa en ciertos casos se hunde a un archivo externo aparte, y en el cuerpo queda solo un puntero de una línea, «ve a verlo cuando lo necesites». El objetivo es mantener la capa de arriba siempre despejada — si amontonas demasiado, la acción que la IA debería ejecutar queda sepultada.

Dos contraejemplos, los dos con nombre:

Desparrame (sprawl): meterlo todo en un solo archivo, cada vez más largo. Aunque cada línea sea correcta y no se repita, el «largo» en sí ya es la enfermedad — la IA tiene que vadear un muro de texto antes de alcanzar el trabajo de verdad.
Sedimento (sediment): lo viejo solo se añade, nunca se borra, y se va apilando capa sobre capa; el que llega después tiene que excavar como un arqueólogo para dar con la parte que aún sirve.

Caso real: grill-with-docs empezó siendo un monolito gordo — la lógica del interrogatorio, el formato de documentos, la plantilla de ADR, todo apretado en un archivo. Matt lo partió en tres: la mitad del interrogatorio salió a grilling, la mitad de escribir documentos salió a domain-modeling, y hasta los archivos de formato de ADR y de glosario se hundieron dentro de domain-modeling; grill-with-docs se quedó como una carcasa fina de una línea que enhebra las dos. Eso es adelgazar una skill inflada con la escalera de información.

Cómo lo usas: cuando termines, vuelve atrás y borra. Por cada línea pregunta «¿esto hace falta en todos los caminos?». Si no — o se hunde a un externo, o se corta directamente. Una intuición tosca pero útil: cuanto más corto sea el SKILL.md, más reducido al tronco, más fiable suele ser.

Regla 3 · Qué palabras usas: tira de conceptos que la IA ya tiene en la cabeza

Esta es la más contraintuitiva; a mí mismo me costó un rato dar el giro.

Palabra que tira del resto (leading word): un concepto que la IA ya aprendió en el entrenamiento y que arrastra consigo toda una red de asociaciones. No se limita a la jerga técnica — videojuegos, terreno militar, medicina, refranes de andar por casa, todo vale, con que la IA lo pille a la primera. Lo escribes en la skill, no lo explicas, y ella saca esa cadena entera de comportamiento.

Ejemplos (todos prestados, ninguno lo inventó Matt):

fog of war (niebla de guerra, de los videojuegos / lo militar) → la IA entiende al instante «delante no se ve nada, actúa con la información parcial que tengas a mano».
tracer bullets (balas trazadoras, de The Pragmatic Programmer) → «abre primero el camino más fino de punta a punta, confirma la dirección y luego añade carne».
triage (triaje, de urgencias del hospital), caveman (cavernícola = hablar poco), grilling (interrogatorio) — coges el concepto ya hecho y lo usas.

Dónde buscarla: primero deja claro el comportamiento que quieres, y luego pregúntate al revés «¿qué palabra o referencia ya hecha significa, ella sola, justo esto?». Pesca en refranes, clásicos, metodologías, videojuegos y terreno militar, medicina y deporte. Todo lo que la IA ha leído es tu vocabulario.

Cómo se verifica — el test del no-op: metes la palabra sola, sin explicación, ¿la IA hizo lo que querías? Si lo hizo = leading word de verdad, estás cobrando gratis lo que la IA ya sabe; si encima tienes que explicártelo un rato para que lo entienda = no está aportando, y cae en uno de los contraejemplos:

Palabra que no hace nada (no-op): la pusiste, pero la IA ya lo haría igual. Por ejemplo «be thorough» (sé minucioso) — la IA por defecto ya es algo minuciosa, esa línea es como no escribir nada. El arreglo no es añadir explicación, es cambiar a una palabra más dura: «be thorough» → «relentless» (implacable).
Duplicación (duplication): lo mismo dicho varias veces. Cuesta de mantener (cambias en un sitio, tienes que cambiar en todos) y además infla el peso de esa idea a ojos de la IA por encima de lo que merece.

Caso real: Matt le metió cuchillo a estos dos de verdad. Apretó la skill review y el mensaje del commit lo dice con todas las letras, «single-sourced rules, no-op cuts» — fundir reglas repetidas, cortar las líneas que no hacían nada. Incluso volvió sobre el propio writing-great-skills para «cazar los no-op a nivel de frase».

Cómo lo usas: no describas el comportamiento con una frase entera, busca una palabra ya hecha que lo enganche; luego saca cada adjetivo y adverbio y pásale el test del no-op — si lo borras, ¿cambia algo en la IA? Lo que no cambie es paja, fuera.

Regla 4 · Cómo cierra: cada paso, un criterio de finalización verificable

Una skill suele ser una sarta de pasos. Si cada paso está hecho o no, lo decide su criterio de finalización (completion criterion).

Un buen criterio de finalización tiene dos exigencias: una, que sea verificable — la IA puede juzgar objetivamente si «está hecho» o «no está hecho», no a ojo; dos, que agote cuando deba agotar — por ejemplo «hay que dar cuenta de cada modelo que se haya tocado», no un vago «haz una lista de cambios».

Contraejemplo · cierre prematuro (premature completion): el criterio queda turbio («llegar a un acuerdo», «entenderlo bien»), la IA no alcanza ningún límite claro, y la atención se le resbala de «terminar el trabajo» a «dar esto por hecho cuanto antes»; se escabulle al siguiente paso sin haber terminado de verdad.

Hay un mecanismo asociado: si la IA ve qué pasos le esperan más adelante, ese tirón de «acabo rápido y sigo» se hace más fuerte. Una forma de contrarrestarlo es esconder los pasos siguientes en otra skill, para que el paso actual no esté pensando en correr.

Caso real: el gesto estrella de grilling (la mitad del interrogatorio que salió de grill-with-docs) es preguntar de una en una, y no pasar a la siguiente hasta que respondes la anterior — su leading word es precisamente «relentless» (implacable). Partir en su día el interrogatorio y la escritura de documentos en dos skills va por lo mismo: que la IA, mientras te interroga, no esté pensando «termino de preguntar y me lanzo a escribir el documento», porque así cierra de cualquier manera. Separados, el paso de interrogar es solo interrogar.

Cómo lo usas: escribe la condición de cierre de cada paso como algo verificable y, mejor, exhaustivo («cada X…», no «más o menos ya»); y si notas que la IA se adelanta siempre en cierto paso, mueve los pasos de después a otra skill.

Con estas cuatro, mira una cosa rara: ¿por qué borró caveman?

Llevemos las cuatro a la escena de un crimen real.

El caveman del que hablamos en el primer artículo (hacer que la IA se calle y vaya al grano) ya no aparece en el repo original de Matt — lo borró. El registro de la eliminación es de lo más sobrio:

A finales de mayo borró entero el SKILL.md de caveman, con un mensaje de commit de una sola palabra: «streamline» (depurar).
Quince días después limpió las referencias que quedaban en el README y en la lista de plugins.
Ninguna skill nueva vino a relevarla. Borrado a secas.

¿Por qué? Con las cuatro reglas en la mano se ve enseguida: caveman es una skill manual, ocupa tu carga cognitiva — tienes que acordarte de que está. Pero lo poco que hace (ahorrar palabras, quitar la cortesía) lo consigues con una sola instrucción, o con un estilo de salida global, y no merece ocupar una de esas «casillas que tienes que recordar». Borrarla es podar a nivel de la colección entera de skills, cortar una carga que no salía a cuenta.

Aclaración honesta: el mensaje del commit de Matt solo decía «streamline», sin explayarse; esto es mi interpretación con este marco. Pero el marco da una explicación que se sostiene sola — y eso es justo para lo que sirve.

Las cuatro no son solo una lista para escribir skills: también explican por qué una skill del mundo real vive o muere.

Chuleta

Regla	Qué hacer	Contraejemplo	Autocomprobación de una frase
Cómo se dispara	description solo si el modelo tiene que alcanzarla solo; si no, manual	carga de contexto ocupada para nada	«esta skill, ¿quién necesita alcanzarla?»
Cuánto metes	en el SKILL.md solo lo que vale para todos los caminos, el resto hundido a externo	sprawl / sediment	«¿esta línea hace falta en todos los caminos?»
Qué palabras usas	tira de un concepto ya hecho como leading word, una palabra ancla un bloque de comportamiento	no-op / duplication	«si borro esta línea, ¿cambia algo en la IA?»
Cómo cierra	cada paso, un criterio de finalización verificable y exhaustivo	cierre prematuro	«¿la IA puede juzgar objetivamente si este paso está hecho?»

Criterio único: predictibilidad — ante la misma situación, la IA recorre siempre el mismo proceso. Las cuatro sirven a eso.

Para cerrar

Cuatro reglas; para escribir skills, aplícalas tal cual. Y aunque no vayas a escribir una skill en tu vida, la forma que hay detrás de «cómo exprimir determinismo de una IA aleatoria» te sirve igual para manejar la IA con más estabilidad en el día a día — al fin y al cabo, eso es lo bueno de robarle el oficio a un crack: no te llevas unas reglas, te llevas su criterio.

Fuente: este artículo desmenuza el writing-great-skills de Matt Pocock (y su GLOSSARY.md), repo mattpocock/skills, licencia MIT, versión 6eeb81b. Los «casos reales» del texto se pueden comprobar en el historial de commits de ese repo (links de commit incluidos).

Misma serie: Primero · caveman · Segundo · grill-with-docs