14. Personalización: agentes, comandos y permisos

Objetivo del tema

Adaptar OpenCode a tu forma de trabajar: definir agentes especializados con su propio prompt, modelo y permisos; crear comandos slash reutilizables para tareas repetitivas; y controlar con precisión qué puede hacer el agente y dónde.

14.1 Los tres niveles de personalización

Todo lo que viste hasta aquí (temas, atajos, proveedores) era configuración superficial. Esta es la capa profunda:

14.2 Crear un agente propio

La forma más cómoda es un archivo Markdown con frontmatter. Colócalo en:

• .opencode/agents/ dentro del proyecto (compartido con el equipo vía Git), o
• ~/.config/opencode/agents/ para disponer de él globalmente.

El nombre del archivo se convierte en el nombre del agente. Ejemplo de un revisor de código de solo lectura:

---
description: Revisa calidad y buenas prácticas del código
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
Estás en modo revisión de código. Enfócate en:
- Calidad, bugs potenciales y casos borde
- Implicaciones de rendimiento
- Consideraciones de seguridad

Ofrece feedback constructivo sin hacer cambios directos.

Guárdalo como .opencode/agents/revisor.md y podrás invocarlo con @revisor desde cualquier conversación.

También existe el asistente interactivo, que genera el archivo por ti preguntando propósito, modo y permisos (todo lo que no autorices queda denegado):

opencode agent create     # guiado
opencode agent list       # lista los agentes disponibles

Pasando todas las banderas (--path, --description, --mode, --permissions, -m) el mismo comando funciona sin interacción, ideal para scripts de onboarding de equipo.

14.3 Opciones de configuración de agentes

También pueden definirse en la sección agent del opencode.json, lo que permite ajustar cada parámetro:

Opciones principales al definir un agente

Opción	Función
description	Obligatoria: describe qué hace el agente y cuándo usarlo (guía la invocación automática).
mode	primary (accesible con Tab), subagent (invocable con @) o all.
model	Modelo propio en formato proveedor/modelo: uno económico para planificar, otro potente para implementar.
temperature	Determinismo: 0.0-0.2 para análisis, 0.6+ para lluvia de ideas.
steps	Límite de iteraciones autónomas antes de resumir y detenerse (control de costos).
prompt	Prompt de sistema propio; admite archivos externos con {file:./prompts/review.txt}.
permission	Matriz de permisos específica del agente (ver 14.4).
hidden	Oculta un subagent del autocompletado @ (solo invocación programática).

14.4 Permisos finos: allow, ask, deny

Cada herramienta acepta tres acciones: "allow" (sin preguntar), "ask" (confirmación humana) y "deny" (bloqueado). Lo potente es combinarlas con patrones:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "edit": "allow",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git push": "ask"
        },
        "webfetch": "deny"
      }
    }
  }
}

• Los patrones tipo glob aplican a comandos bash completos ("grep *", "npm test*") o a rutas de archivos en permisos de edición.
• Con comodines, la última regla que coincide gana: pon primero la regla general "*" y después las excepciones.
• El mismo esquema sirve para herramientas MCP externas ("mimcp_*": "deny").
• El permiso task controla qué subagents puede invocar un agente (útil para orquestadores restringidos).

14.5 Comandos personalizados

Un archivo Markdown por comando, en .opencode/commands/ (proyecto) o ~/.config/opencode/commands/ (global). Ejemplo .opencode/commands/test.md:

---
description: Corre los tests con cobertura
agent: build
---
Ejecuta la suite completa con reporte de cobertura y muestra los fallos.
Concéntrate en los tests que fallan y sugiere correcciones.

Desde ese momento, escribir /test en la TUI ejecuta esa consigna. Las plantillas admiten superpoderes:

• Argumentos: $ARGUMENTS se sustituye por todo lo escrito tras el comando, y $1, $2, $3 por argumentos individuales. Ejemplo: /componente Button crea el componente pedido.
• Salida shell: !`comando` inyecta el resultado real de un comando en el prompt. Un comando /cobertura puede incluir !`npm test -- --coverage` para que el modelo analice los resultados frescos.
• Referencias de archivo: menciona @src/ruta.tsx dentro de la plantilla y su contenido viaja con el prompt.

---
description: Revisa cambios recientes
---
Commits recientes:
!`git log --oneline -10`

Revisa estos cambios y sugiere mejoras.

Opciones adicionales en el frontmatter: model para fijar modelo, y subtask: true para forzar que el comando corra como subtarea sin contaminar el contexto principal. Ojo: un comando personalizado con el mismo nombre que uno integrado (/init, /undo...) lo reemplaza.

Conclusión: con agentes propios, comandos parametrizables y permisos quirúrgicos, OpenCode deja de ser una herramienta genérica para convertirse en la herramienta de tu equipo, con sus estándares codificados y su política de seguridad aplicada. En el próximo tema ampliaremos el arsenal con herramientas externas: servidores MCP, skills y formatters.