writing-great-skills

name	writing-great-skills
description	Referencia para escribir y editar bien los skills — el vocabulario y los principios que hacen a un skill predecible.
disable-model-invocation	true

Un skill existe para arrancarle determinismo a un sistema estocástico. La predictibilidad — que el agente siga el mismo proceso en cada ejecución, no que produzca la misma salida — es la virtud raíz; cada palanca de abajo la sirve.

Los términos en negrita están definidos en glosario.md; buscarlos ahí para el significado completo.

Invocación

Dos opciones, que intercambian costes distintos:

• Un skill invocado por el modelo conserva una description, de modo que el agente puede dispararlo de forma autónoma y otros skills pueden alcanzarlo (tú también puedes seguir escribiendo su nombre). Contribuye a la carga de contexto — la description está en la ventana en cada turno. Mecánica: omitir disable-model-invocation y escribir una description orientada al modelo con fraseo de disparo rico ("Usar cuando el usuario quiera…, mencione…").
• Un skill invocado por el usuario retira la description del alcance del agente: solo tú, escribiendo su nombre, puedes invocarlo — y ningún otro skill puede. Cero carga de contexto, pero gasta carga cognitiva: tú eres el índice que debe recordar que existe. Mecánica: poner disable-model-invocation: true; la description pasa a ser para humanos — un resumen de una línea, sin listas de disparadores.

Elegir invocación por el modelo solo cuando el agente deba alcanzar el skill por su cuenta, u otro skill deba hacerlo. Si solo se dispara a mano, hacerlo invocado por el usuario y no pagar carga de contexto.

Cuando los skills invocados por el usuario se multiplican más allá de lo que puedes recordar, esa carga cognitiva apilada se cura con un router skill: un skill invocado por el usuario que nombra a los demás y cuándo recurrir a cada uno.

Escribir la description

Una description invocada por el modelo hace dos trabajos — decir qué es el skill y listar las branches que deben dispararlo. Cada palabra aumenta la carga de contexto, así que una description se gana una poda aún más dura que el cuerpo:

• Poner por delante la leading word del skill — la description es donde hace su trabajo de invocación.
• Un disparador por branch. Los sinónimos que renombran una misma branch son duplicación — "construir features con TDD … pide desarrollo test-first" es una branch escrita dos veces. Colapsarlos; conservar solo las branches genuinamente distintas.
• Recortar la identidad que ya está en el cuerpo. Limitar la description a los disparadores, más cualquier cláusula de alcance de "cuando otro skill necesite…".

Jerarquía de información

Un skill se construye con dos tipos de contenido — pasos y referencia — que se mezclan libremente: un skill puede ser todo pasos, todo referencia, o ambos. La decisión central es cuál usar y dónde se sitúa cada pieza en la jerarquía de información, una escalera ordenada por cuán inmediatamente necesita el agente el material:

1. Paso en el skill — una acción ordenada en SKILL.md, el nivel primario: qué hace el agente, en orden. Cada paso termina en un criterio de finalización, la condición que le dice al agente que el trabajo está hecho. Hacerlo comprobable (¿puede el agente distinguir hecho de no-hecho?) y, donde importe, exhaustivo ("cada modelo modificado contabilizado", no "producir una lista de cambios") — un criterio vago invita a la finalización prematura.
2. Referencia en el skill — una definición, regla o hecho en SKILL.md, consultado bajo demanda. A menudo un conjunto de pares legítimamente plano (todas las reglas de una revisión en un mismo peldaño) — un arreglo válido, no un smell. Este skill es todo referencia.
3. Referencia externa — referencia empujada fuera de SKILL.md a un archivo aparte, alcanzada por un puntero de contexto, cargada solo cuando el puntero se dispara. (Abarca desde la referencia revelada — un archivo hermano como glosario.md, aún parte del skill — hasta la referencia externa plena que vive fuera del sistema de skills y a la que cualquier skill puede apuntar.)

Un criterio de finalización exigente impulsa un legwork minucioso — la excavación que hace el agente dentro del trabajo — tenga el skill pasos o no, porque "cada regla aplicada" ata la referencia plana igual que "cada paso hecho" ata una secuencia.

Empuja demasiado poco hacia abajo y la cima se hincha; empuja demasiado y escondes material que el agente realmente necesita. Esa tensión es toda la decisión.

La progressive disclosure es el movimiento escalera abajo — fuera de SKILL.md hacia un archivo enlazado — para que la cima siga siendo legible. Mecánica: un archivo .md enlazado en la carpeta del skill, nombrado por lo que contiene (este skill revela sus definiciones completas en glosario.md). Algunos skills se usan de más de una manera, y cada manera distinta es una branch — ejecuciones distintas que toman caminos distintos por el skill. El branching es la prueba de revelado más limpia: inlinear lo que toda branch necesita, y empujar detrás de un puntero lo que solo algunas branches alcanzan. La redacción de un puntero de contexto, no su destino, decide cuándo y con qué fiabilidad el agente alcanza el material.

Donde la escalera decide cuán abajo se sitúa una pieza, la co-ubicación decide qué se sitúa a su lado una vez allí: mantener la definición, reglas y salvedades de un concepto bajo un mismo encabezado en vez de dispersas, para que leer una parte traiga consigo a sus vecinas.

Cuándo dividir

La granularidad es cuán finamente divides los skills, y cada corte gasta una de las dos cargas, así que divide solo cuando el corte lo compense. Dos cortes:

• Por invocación — separar un skill invocado por el modelo cuando tengas una leading word distinta que deba dispararlo por sí sola, u otro skill deba alcanzarlo. Pagas carga de contexto por la nueva description siempre cargada, así que ese alcance independiente tiene que valerlo.
• Por secuencia — dividir una tirada de pasos cuando los pasos que quedan por delante (los pasos post-finalización de un paso) tienten al agente a apresurar el que tiene enfrente (finalización prematura). Mantenerlos fuera de la vista anima al agente a hacer más legwork en la tarea actual.

Poda

Mantener cada significado en una única fuente de verdad: un lugar autoritativo, para que cambiar el comportamiento sea una edición en un solo sitio.

Comprobar cada línea por relevancia: ¿sigue incidiendo en lo que hace el skill?

Luego cazar no-ops frase a frase, no solo línea a línea: aplicar el test de no-op a cada frase en aislamiento, y cuando una falle, borrar la frase entera en vez de recortarle palabras. Ser agresivo — la mayor parte de la prosa que falla debe irse, no reescribirse.

Leading words

Una leading word es un concepto compacto que ya vive en el pretraining del modelo y con el que el agente piensa mientras ejecuta el skill (p. ej. lección, niebla de guerra, balas trazadoras). Repetida a lo largo del texto (aunque no necesariamente — una leading word fuerte puede necesitarse solo una vez), acumula una definición distribuida y ancla toda una región de comportamiento en los mínimos tokens, reclutando priors que el modelo ya posee.

Sirve a la predictibilidad dos veces. En el cuerpo ancla la ejecución: el agente recurre al mismo comportamiento cada vez que aparece la palabra. En la description ancla la invocación: cuando la misma palabra vive en tus prompts, docs y código, el agente vincula ese lenguaje compartido con el skill y lo dispara con más fiabilidad.

Cazar oportunidades de refactorizar skills para usar leading words. Una tríada deletreada en tres sitios (duplicación), una description gastando una frase en señalar una sola idea — cada una es un pasaje pidiendo colapsar en un único token. Ejemplos:

• "rápido, determinista, de baja sobrecarga" -> ajustado — una cualidad reformulada a lo largo de una fase — en una sola palabra preentrenada (un bucle ajustado).
• "un bucle en el que crees" -> red — convierte una compuerta difusa en un estado binario observable (el bucle se pone red con el bug, o no).

Ganas dos veces: menos tokens, y un gancho más afilado del que el agente cuelga su pensamiento. Asume que cada skill carga reformulaciones que las leading words jubilan — ve a encontrarlas.

Modos de fallo

Usarlos para diagnosticar problemas que el usuario pueda estar teniendo con el skill.

• Finalización prematura — terminar un paso antes de que esté genuinamente hecho, la atención resbalando hacia estar terminado. Defensa, en orden: afilar primero el criterio de finalización (barato, local); solo si es irreduciblemente difuso y observas la prisa, esconder los pasos post-finalización dividiendo (el corte por secuencia).
• Duplicación — el mismo significado en más de un lugar. Cuesta mantenimiento y tokens, e infla la prominencia de un significado en la escalera por encima de su rango real.
• Sedimento — capas rancias que se asientan porque añadir se siente seguro y quitar se siente arriesgado. El destino por defecto de cualquier skill sin disciplina de poda.
• Sprawl — un skill simplemente demasiado largo, incluso cuando cada línea está viva y es única. Daña la legibilidad y la mantenibilidad y desperdicia tokens. La cura es la escalera: revelar la referencia detrás de punteros, y dividir por branch o secuencia para que cada camino cargue solo lo que necesita.
• No-op — una línea que el modelo ya obedece por defecto, así que pagas carga para no decir nada. El test: ¿cambia el comportamiento respecto al default? Una leading word débil (sé minucioso cuando el agente ya es más o menos minucioso) es un no-op; el arreglo es una palabra más fuerte (implacable), no una técnica distinta.
• Negación — dirigir por prohibición sale al revés: no pienses en un elefante nombra al elefante y lo hace más disponible, no menos. Prompt en positivo — enunciar el comportamiento objetivo para que el prohibido nunca se pronuncie; conservar una prohibición solo como guardrail duro que no puedas formular en positivo, y aun entonces emparejarla con qué hacer en su lugar.