OpenCode

1. Comando: qué hacer
2. Agente: quién lo va a hacer (Build, Plan u otro) diseñado para tareas específicas o generales
3. Skill: conocimiento al que puede acceder el agente de un concepto específico; especialista en base de datos, frontend, framework, arquitecturas, etc.

Instalación

• Arch Linux

sudo pacman -S opencode

• Windows

bun add -g opencode-ai

Comandos básicos

opencode        # Iniciar OpenCode en la carpeta/proyecto actual
opencode web    # Abrir versión web
/init           # Generar resumen o contexto del proyecto
/thinking       # Switch para mostrar si ver o no la cadena de pensamiento
/undo           # Revertir el ultimo mensaje
@<path>         # Seleccionar archivos o carpetas
!               # Entra al modo bash (util para pasarle el resultado del comando)

Ctrl + Izquierda/Derecha    # Moverse en el prompt
Ctrl + w                    # Eliminar palabra
Ctrl + u                    # Eliminar línea
Ctrl + +/-                  # Zoom
Ctr + P                     # Abrir comandos

Archivo de contexto

• El comando /init genera un resumen o contexto del proyecto; stack de tecnologías, estructura de carpetas, reglas para escribir código, etc. Genera un archivo AGENTS.md que es similar a CLAUDE.md. Este archivo se carga siempre en el contexto. Que sea un mapa y no una enciclopedia
• Overview del proyecto; estructura de carpetas, comandos (test, lint, build) y convenciones, permisos y hooks.
• Las instrucciones en AGENT.md/CLAUDE.md y en las skills son peticiones, no garantías; si algo debe pasar siempre, va en un hook, por ejemplo ejecutar tests antes de dar por terminada una tarea.

Modelos

opencode auth login  # Agregar proveedores
opencode auth logout # Eliminar proveedores
/connect             # Agregar proveedores
/models              # Elegir modelo
Ctrl + T             # Variante del modelo

Agentes

Los agentes son asistentes de IA especializados que se pueden configurar para tareas y flujos de trabajo específicos.

Tab                # Cambiar entre agentes primarios
Ctrl+X + Derecha   # Ver subagentes que se están ejecutando en la sesión
Ctrl+X + Derecha   # Siguiente subagente
Ctrl+X + Izquierda # Subagente anterior
Ctrl+X + Arriba    # Salir de la vista de subagentes a la sesión principal

Tipos de Agente

Primarios

• Los agentes principales son los asistentes con los que se interactua directamente
• Se seleccionan con la tecla Tab

OpenCode incluye dos agentes principales: Build y Plan.

• Build es el agente principal que implementa; comienza a escribir código, editar archivos, ejecutar comandos, etc.
• Plan es un agente restringido, diseñado para la planificación y el análisis, útil cuando se debe analizar el código, sugerir cambios o crear planes sin realizar ninguna modificación en el código. Cuando se trabaja en el modo Plan y se requiere guardar el archivo probablemente no lo permita porque no tiene los permisos, entonces es se debe cambiar al modo Build

Subagentes

• Los subagentes son asistentes especializados que los agentes principales pueden invocar para tareas específicas
• También se pueden invocar manualmente mencionandolo con @ en el mensaje, por ejemplo. @general help me search for this function

Lo que anteriormente se conocía como darle roles al agente o IA con la ingeniería de prompts para que sea más efectivo; Frontend, backend, base de datos, seguridad, etc.

OpenCode incluye tres subagentes: General, Explore y Scout.

• General es un agente de propósito general para investigar preguntas complejas y ejecutar tareas de varios pasos. Tiene acceso completo a todas las herramientas (excepto tareas pendientes), por lo que puede modificar archivos cuando sea necesario. Útil para ejecutar varias unidades de trabajo en paralelo.
• Explore es un agente rápido de solo lectura para explorar bases de código. No puede modificar archivos. Útil cuando se necesita encontrar archivos rápidamente mediante patrones, buscar palabras clave en el código o responder preguntas sobre la base de código.
• Scout es un agente de solo lectura para documentación externa e investigación de dependencias. Útil cuando se necesite clonar un repositorio de dependencias en la caché administrada de OpenCode, inspeccionar el código fuente de una biblioteca o comparar el código local con las implementaciones de la fuente original sin modificar el espacio de trabajo.

Crear agentes

Se pueden crear agentes primarios y subagentes con el comando opencode agent create o agregando el archivo manualmente en la carpeta de configuración de opencode del usuario

Ya que los agentes primarios pueden invocar subagentes, se puede agregar al AGENT.md instrucciones para ejecutar subagentes, por ejemplo; cada vez que se mencione algo relacionado a la seguridad se utilice el subagente de seguridad, o cuando se deba actualizar la documentación se utilice el subagente de documentación, etc.

Sesiones

/new          # Crea sesión (dentro de la misma instancia)
/sessions     # Ver y navegar entre sesiones (sin importar si se cerró)
Ctrl+X + L    # Ver y navegar entre sesiones (sin importar si se cerró)
Ctr + R  |  /rename    # Renombrar sesión
Ctr + D                # Eliminar sesión

• Mientras se están haciendo modificaciones, es posible agregar más mensajes y estos entrarán a la lista de espera o cola, y se irán ejecutando cuando termine la tarea anterior

MCP

• Permite controlar servicios externos con OpenCode
• Similar a una API, pero para IA
• Se pueden habilitar o deshabilitar para que no ocupen mucho contexto
• Se pueden agregar en el archivo de configuración de opencode.jsonc del proyecto, pero algunos MCP necesitan credenciales o API KEY, entonces es preferible agregar los MCP en el archivo de configuración del usuario

/mcps     # Ver MCPs disponibles
    Space     # Habilitar/deshabilitar MCPs

~/.config/opencode/opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "ctx7sk-05b16c38-55f3-427f-a673-76240ceb5885"
      },
      "enabled": true
    },
    "chrome-devtools": {
      "type": "local",
      "command": ["bunx", "-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Utilizando context7 actualiza Better Auth

Crea el register, un usuario y comprueba su funcionamiento con chrome-dev-tools mcp

Agent Skills

• Son instrucciones de como la IA debe comportarse; guías de diseño UI, código de calidad, testing, etc.
• Los Agent Skills permiten que OpenCode descubra instrucciones reutilizables en el repositorio o directorio principal.
• Las skills se cargan bajo demanda mediante la herramienta nativa de skills: los agentes ven las skills disponibles y pueden cargar el contenido completo cuando sea necesario.
• Usar Skills de fuentes confiables, para evitar prompt injection
• Con el comando /skills para ver los Skills agregados

Instalación manual

• Crear una carpeta con el nombre de la skill y dentro colocar un archivo SKILL.md
• Cada SKILL.md debe comenzar con un encabezado YAML y después la definición

Rutas donde OpenCode busca Skills

• Configuración del proyecto: .opencode/skills/<name>/SKILL.md
• Configuración global: ~/.config/opencode/skills/<name>/SKILL.md
• Compatible con Claude a nivel proyecto : .claude/skills/<name>/SKILL.md
• Compatible con Claude a nivel global: ~/.claude/skills/<name>/SKILL.md
• Agentes-compatibles a nivel proyecto: .agents/skills/<name>/SKILL.md
• Agentes-compatibles a nivel global: ~/.agents/skills/<name>/SKILL.md

Ejemplo:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

Instalación con comandos

1. Buscar skills de fuentes confiables como skills.sh
2. Utilizar el comando en la raíz del proyecto
3. Elegir los agentes que se estén utilizando, por defecto ya viene para OpenCode, Codex y otros pero se pueden agregar más, como para Claude Code
4. Para utilizarlo solo se debe hacer referencia en el mensaje

Uso

/<skill-name> crea un dashboard para la administración de usuarios y productos, solo para Admin

Mejora el dashboard utilizando interface-design

Comandos personalizados

• Se guardan en la ruta .opencode/commands/<command-name>.md
• Se ejecuta igual que los demás comandos, /connect /skills /mcp
• Al igual que las skills, los comandos también tienen una estructura definida

Ejemplo:

.opencode/commands/test.md

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Archivo de configuración

• Se puede configurar OpenCode mediante su archivo de configuración
• Temas, atajos de teclado, permisos, modelos, etc.
• Se puede agregar a Git pero teniendo cuidado de no incluir credenciales o API KEY
• Configuración del usuario ~/.config/opencode/opencode.jsonc
• Configuración del proyecto project/opencode.jsonc

Flujo de trabajo con un agente de código (Claude Code / OpenCode)

1. Configuración inicial (una sola vez)

1.1 /init — Generar contexto del proyecto

• Proyecto existente: el agente analiza el código y genera el contexto automáticamente.
• Proyecto nuevo: genera un archivo casi vacío que se va completando conforme se toman decisiones (o se llena manualmente desde el inicio).

El archivo de contexto (AGENTS.md o equivalente) debe incluir:

• Stack: lenguaje, framework, gestor de paquetes, etc.
• Organización de carpetas.
• Qué se va a construir (objetivo del proyecto).
• Comandos clave: test, lint, build.

El agente lee este archivo al inicio de cada sesión, por lo que mantenerlo actualizado es crítico.

1.2 Plan maestro del proyecto

1. Entrar en Plan Mode.
2. Solicitar un roadmap de alto nivel de todo el proyecto, dividido en fases entregables, cada una con su alcance definido.
3. Guardarlo en ROADMAP.md, SPEC.md o PLAN.md.

Ventajas de guardarlo en un archivo:

• Sobrevive a resets o nuevas sesiones de chat.
• Permite retomar el trabajo fácilmente: "Seguimos con la fase 3 del PLAN.md".

Alternativa: guardar el plan vía MCP (ej. un proyecto de Notion) para llevar el seguimiento de features y tareas pendientes en una herramienta externa.

2. Ciclo de trabajo por feature (se repite)

Antes de empezar, verificar si ya existe un archivo de planificación con tareas pendientes; si no, crearlo.

#	Paso	Detalle
1	Plan	Solicitar el plan de la feature con especificidad: qué archivos crea/edita, qué funciones, en qué orden.
2	Revisar y ajustar	Corregir el plan en la conversación antes de ejecutar, para evitar errores como que el agente use algo fuera del stack definido.
3	Aprobar y cambiar a Build Mode	Escribir "proceed" (o equivalente) y dejar que se ejecute.
4	Verificar	El hook corre los tests automáticamente; revisar los archivos modificados.
5	Commit	Commits frecuentes y pequeños.
6	Documentar aprendizajes	Registrar cualquier corrección relevante en AGENTS.md (ver sección 3).

Diagrama del ciclo, incluyendo cambio de modelo

Nueva tarea
   ↓
Plan Mode (modelo SOTA: Opus / GPT-5.5)
   ↓
Plan aprobado
   ↓
Cambiar a Build Mode + modelo económico
   (Sonnet / GPT-5.5 mini / Kimi)
   ↓
Implementación
   ↓
¿Surge un problema complejo? ──sí──→ Cambiar temporalmente al modelo SOTA → Resolver
   │                                                                            │
   no                                                                           ↓
   ↓                                                              Volver al modelo económico
Continuar implementación ←─────────────────────────────────────────────────────┘

Idea clave: usar el modelo más potente (SOTA) para planificar y para resolver bloqueos difíciles, y un modelo más económico para la implementación rutinaria.

3. Mejoras graduales vía AGENTS.md

Cuando el agente comete un error de suposición sobre el plan (usa una herramienta fuera del stack, una estructura de carpetas distinta, etc.), no basta con corregirlo puntualmente para esa tarea: conviene agregar una regla explícita a AGENTS.md.

• Cada regla nueva reduce la probabilidad de que el error se repita.
• Con el tiempo, a medida que se acumulan features y reglas, el agente comete cada vez menos errores de contexto y necesita menos correcciones manuales.

En resumen: AGENTS.md es un documento vivo que mejora con cada iteración del ciclo.

Recomendaciones

• No pedirle al agente que ejecute un comando común como iniciar el servidor (bun dev), comandos de git, etc. porque consumen tokens.
• Si al solicitar una revisión o cambio ya se sabe en qué archivo va a trabajar, es mejor enlazarlo directamente @path/to/file