Skills e instrucciones

Cuando trabajas con un agente de IA, el modelo no es lo único importante, también lo es las instrucciones que le das. Un agente bien configurado marca la diferencia entre respuestas genéricas y resultados precisos 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.

📌 Si es tu primera vez con OpenCode, empieza primero por leer la guía de OpenCode. Esta guía deberías verla después de conocer bien Opencode.

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:

• Instrucciones del modelo: el comportamiento base del agente seleccionado (build, plan...).
• Herramientas disponibles: descripción de cada herramienta (read, edit, grep, glob, write...).
• Reglas del proyecto: el contenido de AGENTS.md (y posibles instrucciones adicionales).
• Skills cargados: si el agente invocó algún skill, su contenido se inyecta al contexto.

El system prompt no es editable directamente en opencode, 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:

• En la carpeta global de configuración: ~/.config/opencode/AGENTS.md (global).
• En la raíz del proyecto, fuera de src/: AGENTS.md (aplica a todo el proyecto).
• En cualquier subcarpeta dentro de src/: AGENTS.md (aplica a la carpeta y subcarpetas).

Opencode leerá inicialmente el AGENTS.md global y el AGENTS.md del raíz (si existen). Estos son los AGENTS.md que siempre se leerán. Luego, irá leyendo bajo demanda los AGENTS.md que existan en la carpeta donde está trabajando cuando opencode necesite o trabaje con archivos de esa ruta. Irá incorporando cada AGENTS.md de cada carpeta y sus padres hasta llegar al raíz.

El AGENTS.md debe incluir:

• 1️⃣ Comandos importantes y tareas de build, lint y/o test.
• 2️⃣ Estructura del proyecto y convenciones de código.
• 3️⃣ Guías de estilo específicas del equipo.
• 4️⃣ No tengas más de 200 líneas de instrucciones.

💡 Puedes crear un AGENTS.md ejecutando el comando /init desde opencode, que escanea tu proyecto y genera el archivo automáticamente.

📌 OJO: Las referencias a instrucciones adicionales (por ejemplo, usando @ruta/archivo.md) no funcionarán en Opencode V2. Si quieres añadir archivos adicionales, lo mejor es utilizar el campo instructions de tu fichero de configuración opencode.jsonc:

{
  "instructions": [
    "CONTRIBUTING.md",              /* Un archivo concreto */
    "docs/style-guide.md",          /* Un archivo en ruta concreta */
    "docs/**/*.md",                 /* Todos los .md de docs/ */
    "https://dominio.com/style.md"  /* Desde URL */
  ]
}

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. Recuerda colocarlo en instructions, como mencionamos antes, para que lo lea.

Un ejemplo de estructura podría ser el siguiente:

Veamos ahora el contenido de nuestro AGENTS.md:

# Reglas

- No levantes servidores de desarrollo ni hagas builds salvo que se pida.
- No elimines ficheros ni carpetas sin confirmación.
- No instales dependencias sin preguntar.
- No realices acciones irreversibles sin confirmación.

Las ventajas de este enfoque:

• Mantén AGENTS.md conciso y ordenado (entre 10-200 líneas máximo).
• Cada guía es un fichero independiente, fácil de mantener y versionar.
• El agente solo carga los archivos relevantes para la tarea actual.
• Ideal para equipos: cada fichero puede ser responsable de un área.

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/, no solo en la carpeta .opencode del proyecto.

Veamos un ejemplo de un skill:

---
name: git-release
description: Crear versiones y changelogs de forma consistente
---

## Que hacer

- Redactar notas de versión a partir de los PR fusionados
- Proponer un incremento de versión
- Proporcionar un comando `gh release create` listo para copiar y pegar

## Cuando usar

- Úsame cuando estés preparando una versión tag
- Haz preguntas de aclaración si el esquema de versionado no es claro

Los campos name y description del fichero de skills son obligatorios.

• El name debe estar en minúsculas, con guiones para separar, de 1 a 64 caracteres.
• El name debe coincidir con el nombre de la carpeta.
• El description debe contener de 1 a 1024 caracteres. Define qué hace el skill y cuándo usarlo.

⚠️ Ten mucho cuidado al utilizar skills. Hay muchos skills interesantes por Internet que podemos descargar y utilizar para personalizar nuestro agente. Pero, como siempre, puede 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:

• System prompt: se construye automáticamente. No se edita directamente.
• AGENTS.md: reglas del proyecto. El punto de entrada principal para instruir al agente.
• Instrucciones adicionales: ficheros markdown en AGENTS.md adicionales o en instructions.
• Skills: comportamientos reutilizables que el agente carga bajo demanda.

Combinados, estos mecanismos permiten crear agentes altamente personalizados y adaptados a las necesidades de cada proyecto y equipo.

📌 Si quieres llevar esto más allá, la guía de SDD (Spec Driven Development) explica cómo usar AGENTS.md como constitución del proyecto y escribir una especificación por cada feature.