Hype-Generator 3000™: It's a game-changer
Cómo configurar el comportamiento de un agente de IA con instrucciones y reglas en ficheros Markdown.
Cuando trabajas con un agente de IA, no solo importa el modelo que uses, sino también cómo le instruyes. Un agente bien configurado puede marcar la diferencia entre respuestas genéricas y resultados precisos, relevantes y adaptados a tu proyecto.
Un agente como opencode ofrece varias capas de personalización que se combinan para construir las instrucciones generales que recibe el modelo. Desde un archivo simple hasta skills reutilizables, cada nivel permite un mayor control sobre el comportamiento del agente.
El system prompt es la instrucción base que opencode envía al LLM en cada sesión. Define el comportamiento del agente: qué herramientas tiene disponibles, cómo debe actuar y qué reglas seguir.
El agente construye el system prompt automáticamente combinando:
El system prompt no es editable directamente, pero se puede configurar indirectamente a través de los agentes y las instrucciones que mencionaremos a continuación.
AGENTS.md es un archivo markdown que contiene instrucciones personalizadas prioritarias para el LLM. Este archivo puede existir en varios lugares:
src: AGENTS.md (aplica al proyecto)~/.config/opencode/AGENTS.md (aplica a todo)El AGENTS.md debe incluir:
@ruta/archivo.md)Puedes crear un
AGENTS.mdejecutando el comando/initdesde opencode, que escanea tu proyecto y genera el archivo automáticamente.
Con opencode también puedes cargar automáticamente los archivos Markdown que tengas en el campo instructions de tu fichero de configuración opencode.json, desde múltiples rutas o incluso desde una URL remota:
Esto es útil para reutilizar reglas existentes sin duplicarlas, compartir convenciones o cargar instrucciones remotas desde URLs (con timeout de 5 segundos, cuidado con páginas lentas).
Una práctica común es crear una carpeta docs/ en el proyecto con ficheros markdown que contengan instrucciones específicas y detalladas. Estos archivos se referencian desde AGENTS.md usando la sintaxis @docs/filename.md para que el agente los lea bajo demanda.
Un ejemplo de estructura podría ser el siguiente:
Veamos ahora el contenido de nuestro AGENTS.md:
Las ventajas de este enfoque:
AGENTS.md conciso y ordenado (Entre 10-200 líneas máximo)Los skills son definiciones reutilizables de comportamiento que el agente puede cargar bajo demanda usando la herramienta skill. A diferencia de las instrucciones anteriores, los skills no se cargan por defecto.
El agente sólo tiene un índice con el título y descripción breve de cada skill, y decide cuándo cargarlos si la tarea está relacionada por su descripción. Esto permite que el agente tenga un comportamiento más flexible y adaptativo, sin sobrecargarlo con información irrelevante.
La estructura de archivos de nuestro proyecto sería la siguiente:
Los skills también se pueden buscar globalmente en ~/.config/opencode/skills/, o en ~/.agents/skills/, no solo en la carpeta .opencode del proyecto.
Veamos un ejemplo de un skill:
Los campos name y description del fichero de skills son obligatorios.
Ten mucho cuidado al utilizar usar skills. Hay muchos skills interesantes por Internet que podemos descargar y utilizar para personalizar nuestro agente. Pero como siempre, pueden haber skills que no sean seguros o que tengan instrucciones maliciosas que puedan ser dañinas. Usa solo skills de confianza y que hayan sido revisados.
Estas son las 4 capas de personalización que opencode ofrece, de menor a mayor especificidad:
docs/ referenciados desde AGENTS.md con @.Combinados, estos mecanismos permiten crear agentes altamente personalizados y adaptados a las necesidades de cada proyecto y equipo.