No es solo formato

Cuando oyes hablar de Markdown, lo más habitual es pensar en documentación de GitHub, archivos README o textos en Discord. Algo técnico, propio de desarrolladores.

Para mí, ha acabado siendo otra cosa: la manera en que me comunico con mis agentes de IA cada día.

No hablo de escribir documentación bonita. Hablo de utilizar Markdown como un lenguaje para explicar a un agente qué quiero que haga, con qué contexto, en qué orden y con qué límites.

Por qué Markdown y no texto plano

Puedes escribirle a un agente de IA en texto plano. Funciona para cosas sencillas. Pero cuando la tarea tiene varias partes —contexto, instrucciones, ejemplos, restricciones— el texto plano se vuelve difícil de seguir.

Un mensaje largo sin estructura es complicado de leer para una persona y también lo es para una IA. Los modelos no procesan de la misma manera un bloque de texto que un documento con secciones, listas y jerarquía.

Markdown aporta estructura sin complicaciones. Un encabezado marca una sección. Una lista ordena los pasos. Un bloque de código separa un ejemplo del resto. Y todo esto ayuda al modelo a entender qué es contexto, qué es una instrucción y qué es un límite.

Lo que utilizo cada día

Mis agentes se guían por documentos en Markdown. Los skills son archivos .md con una estructura fija: qué son, cuándo se utilizan, qué pasos hay que seguir y qué errores se deben evitar. Los templates son Markdown con variables. Las instrucciones recurrentes las guardo como notas en Markdown.

No lo hice por diseño, sino por necesidad. Cuando empecé a delegar tareas a los agentes, las instrucciones en texto plano generaban más errores, más idas y venidas y más correcciones. Cuando pasé esas mismas instrucciones a Markdown, el resultado mejoró notablemente.

Listas, bloques y orden

Cuando doy instrucciones a un agente, las escribo en listas numeradas. No porque me guste el formato, sino porque una lista impone un orden. El paso 1 va antes que el paso 2. Si el agente sigue esta lista, no se deja nada por el camino. Los bloques de código sirven para dar ejemplos concretos. Si quiero que un agente actualice un proyecto a través de la API, le escribo exactamente el curl que debe ejecutar, dentro de un bloque de código y como parte de la instrucción. No le digo «haz un curl a este endpoint»; le escribo el curl completo. La diferencia en el resultado es clara.

Y los encabezados separan secciones: contexto, instrucciones, restricciones. Si todo está en un solo párrafo, el modelo puede mezclar las instrucciones con el contexto. Si cada cosa tiene su sección, las mantiene separadas.

El frontmatter como contexto

Una cosa que he aprendido trabajando con Astro y con el portfolio es que el frontmatter de un archivo Markdown —aquella cabecera entre guiones con pares clave-valor— es una manera muy eficiente de proporcionar contexto. Un archivo Markdown con frontmatter no es solo texto. Es texto con metadatos: idioma, fecha, categoría, estado. Y estos metadatos indican al agente, antes de leer nada, qué tiene entre manos.

Es como la cabecera de un correo: antes de leer el mensaje ya sabes de quién viene, cuándo ha llegado y de qué asunto trata. Cuando un agente lee el frontmatter de un documento, ya tiene contexto antes de empezar.

Lo que no es

Escribir en Markdown para agentes de IA no es lo mismo que documentar código. No busca ser bonito ni exhaustivo. Busca ser claro y funcional.

No hace falta explicarlo todo. Hay que dar la información suficiente para que el agente sepa qué debe hacer, sin información innecesaria. Un documento de 200 líneas que repite lo mismo en tres sitios es peor que uno de 50 líneas que va directo al grano.

Cuando basta con texto plano

No todo necesita Markdown. Si la tarea es sencilla —«revisa este texto y dime qué te parece» o «comprueba que este servidor responde»—, un mensaje claro en texto plano funciona bien.

El problema aparece cuando la complejidad crece y sigo escribiendo de la misma manera. Si la tarea tiene varias partes, depende de un contexto específico o tiene restricciones importantes, el texto plano se queda corto. Es aquí donde la estructura de Markdown marca la diferencia.

No se trata de utilizar Markdown siempre. Se trata de saber cuándo el texto plano ya no es suficiente.

Lo que me ha enseñado

Aprender a escribir en Markdown me ha enseñado a pensar de una manera más estructurada. Cuando separas el contexto de las instrucciones, ordenas los pasos y distingues lo que es importante de lo que es accesorio, no solo lo haces mejor para la IA: también lo haces mejor para ti.

Ahora, cuando escribo un correo, una instrucción para un compañero o un documento técnico, pienso en secciones, orden y claridad. No porque Markdown me lo imponga, sino porque he comprobado que, cuando algo está bien estructurado, todo el mundo lo entiende mejor.