OpenCode en producción: agentes, habilidades y proyectos reales

Han pasado varias semanas desde el post anterior sobre OpenCode. En ese momento compartía una configuración que había estado ajustando durante un par de meses. La idea central se mantiene: un agente principal que orquesta sub-agentes especializados, habilidades que encapsulan conocimiento, permisos restrictivos para mantener control.

Lo que no sabía entonces es que esa configuración inicial era solo el punto de partida. Lo que vino después fue un refinamiento constante impulsado por proyectos reales, no por experimentos. Y quiero contar cómo ha evolucionado todo desde esa primera versión.

El agente coder hoy

En el post anterior mostré la configuración base del agente coder con sus sub-agentes. Esa estructura se mantiene, pero las instrucciones del agente principal cambiaron bastante. Aprendí que un prompt demasiado genérico produce resultados genéricos. Hoy las instrucciones incluyen reglas específicas sobre:

• Cómo interpretar y aplicar las habilidades cargadas.
• Cuándo delegar en sub-agentes y cómo interpretar lo que reportan.
• El formato exacto de los reportes que debe devolver al final de cada tarea.
• La obligación de escribir una especificación técnica para funcionalidades no triviales antes de tocar código.

Cada sub-agente también evolucionó. El de calidad ahora detecta automáticamente el lenguaje del proyecto antes de ejecutar las herramientas. El de seguridad aprendió a revisar no solo secretos en git, sino también puertos expuestos en Dockerfiles y dependencias con vulnerabilidades conocidas. El de versiones analiza el tipo de cambio (funcionalidad, corrección, refactorización) y sugiere el mensaje de commit apropiado.

Los sub-agentes se definen en archivos separados con un encabezado YAML, como mostré antes, pero las instrucciones se volvieron más precisas. Por ejemplo, el agente de calidad hoy se ve así:

---
description: Runs linters, type checkers, and tests to verify code quality
mode: subagent
temperature: 0.1
permission:
  read: allow
  edit: deny
  bash: allow
---

You are the quality assurance sub-agent.

1. Detect the project language (Python, JS, Go, etc.) by checking
   pyproject.toml, package.json, go.mod, or similar.
2. Run the appropriate linter (ruff for Python, eslint for JS, etc.).
3. Run the type checker if a config exists.
4. Run tests with the project's test framework.

Summarize findings clearly. Do NOT edit files.
Report results to the calling agent.

Parece un cambio menor, pero la detección automática del lenguaje evitó errores tontos como intentar ejecutar ruff en un proyecto de Node.js.

Las habilidades: el mayor multiplicador de productividad

Si hay algo que ha marcado la diferencia, son las habilidades (skills, en la jerga de OpenCode). Al inicio tenía dos o tres. Hoy tengo una docena, y cada una representa una lección aprendida en un proyecto real.

Estas son las que he construido hasta ahora:

docker — Mejores prácticas para construir imágenes, seguridad, caché de capas y docker-compose.
fastapi — Patrones de FastAPI con Pydantic v2, dependencias, ciclo de vida y middleware.
testing — Pytest, fixtures, pruebas asíncronas y estrategias de simulación.
automation — CI/CD, Makefiles y scripts de automatización.
sdd — Spec-Driven Development: escribir especificaciones antes de codificar.
django — Modelos, panel de administración, migraciones, permisos y señales.
nvim — Atajos y flujos de trabajo en Neovim con LazyVim.
zellij — Atajos y organización de paneles en el multiplexor de terminal.

Cada habilidad se guarda en ~/.config/opencode/skills/<nombre>/SKILL.md con un encabezado que permite a OpenCode descubrirlas automáticamente:

---
name: docker
description: Docker best practices for Python projects — multi-stage builds, security, layer caching, and compose patterns.
---

# Docker

## Estructura recomendada
- Usar Dockerfile multi-stage para reducir tamaño de imagen
- Imagen base: python:3.14-slim
- Cache de pip con --no-cache-dir

## Seguridad
- No ejecutar como root: USER appuser
- No exponer puertos innecesarios
- Usar COPY --chown para permisos explícitos
- ...

Lo interesante es que varias de estas habilidades las escribí mientras trabajaba en proyectos que las requerían. La de Docker nació cuando estaba construyendo StirlingPDFAssistant. La de testing cuando quickqr-cli necesitaba pruebas automatizadas. No son teoría: son experiencia empaquetada.

Si quieres explorar habilidades listas para usar, skills.sh es un directorio comunitario con cientos de archivos compatibles con OpenCode. Ahí puedes encontrar desde mejores prácticas para frameworks hasta seguridad y más.

Tres proyectos, un flujo

La mejor forma de mostrar cómo funciona esto en la práctica es con ejemplos reales. Estos son tres proyectos públicos que construí con el mismo flujo de agente coder, sub-agentes y habilidades.

quickqr-cli

quickqr-cli es un script en Python para generar códigos QR desde URLs y números de teléfono. Usa Typer para la interfaz de línea de comandos y qrcode[pil] para generar las imágenes. Un proyecto pequeño y enfocado, ideal para probar el flujo básico.

El agente cargó la habilidad de testing, generó el CLI con Typer, integró la biblioteca qrcode, implementó la detección automática de números telefónicos, y delegó en el sub-agente de calidad para pasar ruff y pytest. Todo el ciclo, desde que di la instrucción hasta que el código pasó todas las verificaciones, tomó menos de lo que me habría tomado hacerlo a mano.

StirlingPDFAssistant

StirlingPDFAssistant es un bot de Telegram para operaciones PDF a través de una instancia propia de Stirling PDF. Está hecho con python-telegram-bot y httpx, corre en Docker con construcción multi-etapa y está diseñado para Raspberry Pi.

Aquí la habilidad de Docker fue clave: el agente sabía exactamente qué imagen base usar (python:3.14-slim), cómo estructurar la construcción multi-etapa, cómo no ejecutar como root, cómo optimizar el caché de capas. Sin la habilidad, habría generado un Dockerfile genérico. Con ella, el resultado fue un contenedor optimizado y seguro desde el primer intento. El sub-agente de seguridad detectó que un puerto de depuración estaba expuesto en el docker-compose y lo reportó antes de hacer commit.

voxlyn-ai

voxlyn-ai es el proyecto más complejo de los tres. Un asistente de voz para Linux que integra faster-whisper para transcripción, kokoro para síntesis de voz, mempalace para memoria conversacional, y un agente OpenCode como cerebro. Todo como un servicio persistente con socket Unix.

Para este proyecto, el flujo fue diferente: primero el agente escribió una especificación técnica detallada (gracias a la habilidad de SDD) donde definió la arquitectura, el flujo de datos, los componentes y las decisiones de diseño. Solo después de que revisé y aprobé la especificación, comenzó a escribir código. El sub-agente de calidad ejecutó pytest y ruff. El de seguridad revisó que no hubiera rutas fijas a modelos ni llaves de API expuestas. El de versiones generó mensajes de commit convencionales para cada funcionalidad.

Los tres proyectos comparten el mismo patrón: yo definí el qué, el agente se encargó del cómo, los sub-agentes verificaron la calidad y seguridad, y al final obtuve código que no solo funciona, sino que sigue las mejores prácticas que yo mismo definí.

Lecciones aprendidas

Después de varios proyectos completados con este flujo, esto es lo que puedo confirmar:

La temperatura baja en sub-agentes no es negociable. Un sub-agente creativo es un sub-agente impredecible. Para tareas de revisión y verificación, temperatura 0.1 o menos garantiza que el resultado sea consistente cada vez. El agente principal puede tener más libertad creativa; los sub-agentes deben ser máquinas precisas.

Los permisos restrictivos salvan vidas. Que los sub-agentes no puedan editar archivos sin aprobación no es una limitación, es una decisión de diseño. El agente de calidad ejecuta herramientas y reporta; el de seguridad escanea y reporta; el de versiones analiza y sugiere. Ninguno modifica código. Las únicas ediciones las hace el agente principal, y yo las reviso antes de que lleguen a GitHub.

Las habilidades son mejores que la documentación tradicional. Una habilidad no es solo una guía de referencia. Es un conjunto de instrucciones que el agente sigue activamente. Cuando documentas una decisión técnica en una habilidad, no queda olvidada en una wiki: se aplica en cada proyecto que la use. Con el tiempo, se han convertido en mi memoria institucional personal.

La especificación antes del código no es opcional. Para proyectos no triviales, la habilidad de SDD obliga al agente a escribir una especificación antes de escribir una línea de código. Esto ha evitado malentendidos y retrabajos. Revisar una especificación me toma minutos; revisar código mal dirigido me tomaba horas.

OpenCode Zen + DeepSeek es más que suficiente. No necesitas el modelo más caro para ser productivo. El plan gratuito de OpenCode con DeepSeek v4 Flash Free ha corrido todos estos proyectos sin problemas. La velocidad es buena, la calidad del código es consistente, y el límite de uso nunca ha sido un problema en mi día a día.

Lo que aún estoy ajustando

No todo ha sido perfecto. Hay áreas donde el flujo sigue evolucionando:

• Instrucciones demasiado largas: Al inicio quería cubrir todos los casos posibles en un solo prompt. Descubrí que los textos largos diluyen las instrucciones importantes. Hoy prefiero prompts cortos y precisos, y habilidades para el contexto adicional.
• Exceso de automatización: Intenté que el agente tomara decisiones de diseño por sí solo. Fue un error. El agente puede implementar, pero las decisiones importantes de arquitectura siguen siendo mías. Aprendí a ser explícito sobre qué quiero que decida y qué quiero que solo ejecute.
• El archivo AGENTS.md: Es la pieza más infravalorada de la configuración. OpenCode genera uno al hacer /init en un proyecto, pero he aprendido a enriquecerlo con detalles específicos: estructura del proyecto, convenciones de código, tecnologías utilizadas, comandos de prueba. Invertir diez minutos en un buen AGENTS.md al inicio de un proyecto multiplica la calidad de las respuestas del agente.

Para cerrar

Han pasado varias semanas desde el primer post, y el cambio más grande no está en la herramienta sino en mi forma de trabajar. Hoy empiezo un proyecto y sé que el agente va a manejar la estructura base, las pruebas, las revisiones de seguridad. Yo me concentro en la arquitectura, en las decisiones difíciles, en lo que realmente requiere criterio humano.

La IA no viene a reemplazarte. Viene a quitarte el trabajo tedioso para que puedas concentrarte en lo que realmente importa. No es teoría: lo he comprobado en tres proyectos públicos, docenas de funcionalidades, y un flujo que mejora con cada uso. El factor diferenciador no es el modelo, ni la herramienta. Es cómo configuras todo para que trabaje contigo, no por ti.

Gracias por llegar hasta aquí. Nos vemos en el próximo post.