La habilidad /writing-for-agents

Fuente: The /writing-for-agents Skill — traducción comunitaria no oficial al español.

Qué hace

writing-for-agents es la referencia contra la que escribes documentos que leen agentes: una habilidad, un AGENTS.md / CLAUDE.md, una spec, un prompt de ejecución, un README, cualquier documento que un agente lee. El empaque difiere; la escritura no: las mismas palancas hacen predecible cada uno, para que el agente siga el mismo proceso cada ejecución en lugar de producir la misma salida.

Su movimiento predeterminado es borrar, no explicar. Pídele a un agente que escriba instrucciones para otro agente y gastará la mayoría de sus palabras explicando lo que el modelo ya sabe. Cada una de esas líneas es un no-op, que paga contexto y no cambia ningún comportamiento. Esta referencia es la lente que las encuentra, por eso rinde al menos tan a menudo sobre un documento que ya tienes como sobre un archivo en blanco.

Se llamó writing-great-skills hasta v1.1. El renombre refleja lo que siempre fue debajo: casi nada de ello es específico de habilidades. La mecánica solo de habilidades (frontmatter, la elección de invocación por modelo frente a por usuario, habilidades router) está revelada en un SKILL-MECHANICS.md enlazado que solo lees cuando el documento que tienes delante es una habilidad.

Cuándo usarla

Escribe /writing-for-agents, o el agente la usa por su cuenta cuando estás creando o editando una habilidad, o modificando AGENTS.md o CLAUDE.md.

Úsala a mano para todo lo demás que un agente lee: tus documentos, specs y tickets, prompts de sistema y AFK. La prueba es una pregunta: ¿esto lo lee un agente? Y no importa cómo llega delante de él, si un puntero lo nombra, un humano lo pega, o simplemente está en el repositorio. Para averiguar qué contiene realmente una base de código en primer lugar, usa grill-with-docs; esta referencia gobierna cómo se lee un documento, no lo que sabe.

Las dos cargas

La idea sobre la que gira toda la referencia es un par de presupuestos que cada documento y puntero gasta:

• Carga de contexto: el costo del material siempre cargado sobre la ventana del agente: una línea de AGENTS.md, una descripción de habilidad, cualquier cosa en contexto cada turno dispare o no.
• Carga cognitiva: el costo sobre ti, es decir qué documentos existen y cuándo usar cada uno. Tú eres el índice. No es un costo a minimizar: es el precio de la agencia humana.

Una vez que piensas en estas dos cargas, la mayoría de las decisiones de autoría (dividir o no, incluir o revelar, apuntar o empujar) se vuelven el mismo intercambio hecho en distintos lugares.

Las palancas

• Punteros de contexto: la referencia guardada en contexto que nombra material fuera de contexto y codifica cuándo alcanzarlo. Una descripción de habilidad y una línea de AGENTS.md que nombra un documento son el mismo objeto; la redacción del puntero, no su objetivo, decide cuán confiablemente el agente lo atraviesa.
• Jerarquía de información: la escalera desde paso en el archivo, a referencia en el archivo, a referencia revelada tras un puntero. La revelación progresiva es el movimiento escalera abajo para que la cima siga legible.
• Criterios de finalización: la claridad y exigencia de la condición de hecho de cada paso, y el trabajo de campo que esa exigencia impulsa; la defensa contra la finalización prematura.
• Palabras iniciales: un concepto compacto ya en el preentrenamiento del modelo (tight, red, tracer bullet) con el que el agente piensa mientras ejecuta el documento. Ancla dos veces: ejecución en el cuerpo, invocación en el puntero.
• Poda: fuente única de verdad, relevancia, y la prueba de no-op aplicada frase por frase, contra duplicación, sedimento y expansión.

Preguntas comunes

¿A dónde se fue /writing-great-skills? Es esta habilidad, renombrada en v1.1. Los practicantes ya la apuntaban a AGENTS.md, documentos, specs, tickets y prompts de ejecución mucho antes de que el nombre la alcanzara; estructura, palabras iniciales y poda resultan ser el oficio de cualquier texto que un agente lee. No hay alias. Reinstala con el nuevo nombre.

“Writing for agents”: ¿entonces el agente escribe? Al revés. Tú eres el autor; el agente es el lector. Esa es toda la dificultad del género: escribes para un lector que ya ha leído todo, así que la explicación es desperdicio y la precisión es todo el trabajo.

¿No puedo pedirle al agente que lo escriba por mí? Puedes, y producirá algo verboso. Solo el modelo explica lo que ya sabe, y no aplicará la prueba de no-op ni buscará una palabra inicial por su cuenta. Usa la referencia sobre el borrador: un pase de revisión es donde cae la mayor parte de su valor.

Le pedí a un agente que recortara un documento y cortó la funcionalidad. A los agentes a los que se les dice “simplifica” optimizan longitud, porque la longitud es lo que pueden ver. La prueba de no-op es conductual, no estética: borra la línea y pregunta si el comportamiento del agente cambió. Cuando una frase falla, borra toda la frase en lugar de recortar palabras, y resuelve un desacuerdo sobre ella ejecutando el documento, no discutiendo.

¿Cómo sé cuándo está hecho? Cuando funciona, y ya no encuentras duplicación, sedimento ni no-ops. No hay evaluación automatizada aquí; la comprobación es una ejecución manual más el vocabulario de modos de fallo como diagnóstico. Cuando un documento se porta mal, ese vocabulario también es el kit de reparación: nombra primero el modo de fallo, luego corrige eso.

¿Esto debería vivir en CLAUDE.md o en otro sitio? Pregunta qué carga quieres pagar. CLAUDE.md carga en cada sesión incondicionalmente; el material tras un puntero solo cuesta la propia línea del puntero hasta que dispara. Cualquier cosa que aplique en un contexto de cada diez está pagando carga de contexto las otras nueve veces.

¿Tengo que reescribir mis documentos para cada modelo nuevo? Mayormente no, y sobreajustar a un modelo es su propia trampa. Actualizar para un modelo nuevo suele ser otro pase de no-op en lugar de una reescritura.

Mi habilidad solo funciona en la tarea exacta desde la que la construí. La ruta común (hacer el trabajo una vez, luego pedir al agente que lo redacte como habilidad) sobrepondera esa ejecución, y los ejemplos salen demasiado específicos. Guarda la ejecución como evidencia, luego abstrae deliberadamente: quita lo que pertenecía a ese repositorio y esos archivos, y escribe para la clase de tarea.

El inglés no es mi primer idioma. ¿Pierdo la ventaja de la palabra inicial? No. Encontrar la palabra que empaqueta más comportamiento en menos tokens es trabajo que la referencia hace por ti. Es una de las cosas para las que sirve.

Funciona si

• El documento se acorta a medida que mejora, y te sorprende lo poco que queda.
• Puedes señalar una palabra inicial y verla trabajar en más de un lugar.
• Nada está dicho dos veces, en ninguna forma. La duplicación es la señal más confiable de que un documento nunca se probó.
• La referencia que solo una rama necesita está tras un puntero en lugar de en el archivo principal.

Dónde encaja

Esta es una referencia independiente para usar cuando quieras. No tiene vecino en la cadena porque está debajo de todo el conjunto en lugar de junto a una habilidad: cada habilidad aquí se escribió contra ella, y los documentos que las otras habilidades dejan atrás (un CONTEXT.md y sus ADR, una spec, un ticket) son exactamente el texto que gobierna una vez que un agente tiene que leerlos. Cuando no estés seguro de qué habilidad o flujo encaja en una tarea, ask-matt te dirige por todo el conjunto.