Capitulo 14: Comandos Custom

< Volver al Indice del Tutorial

Que son los Comandos Custom

Los comandos custom son slash commands propios que ejecutan un prompt predefinido. En lugar de escribir instrucciones largas cada vez que necesitas una tarea recurrente, defines un comando una vez y lo invocas con /nombre desde la TUI.

Son el equivalente a aliases de bash pero para prompts del agente AI.

Configuracion

Los comandos se definen en opencode.json bajo la clave "commands":

{
  "commands": {
    "/review": {
      "description": "Revisar codigo del ultimo commit",
      "prompt": "Revisa los cambios del ultimo commit. Busca problemas de seguridad, performance y calidad. Genera un reporte con hallazgos."
    }
  }
}

Cada comando tiene tres partes:

• nombre: empieza con /, es lo que escribes en la TUI
• description: texto que aparece en el autocompletado
• prompt: el prompt que se envia al agente cuando invocas el comando

Uso desde la TUI

Dentro de la interfaz TUI de OpenCode, simplemente escribe el nombre del comando:

> /review

OpenCode reemplaza /review con el prompt configurado y lo envia al agente. Es equivalente a escribir el prompt completo manualmente.

Los comandos aparecen en el autocompletado cuando escribes /, junto con los comandos nativos de OpenCode.

Templates con Variables

Los prompts pueden incluir contexto dinamico del proyecto. Puedes referenciar archivos, rutas y otros elementos:

{
  "commands": {
    "/test": {
      "description": "Generar tests para un archivo",
      "prompt": "Genera tests unitarios para el archivo que te indique. Usa las convenciones del proyecto: vitest, archivos en __tests__/, patron AAA."
    },
    "/explain": {
      "description": "Explicar arquitectura del proyecto",
      "prompt": "Explica la arquitectura de este proyecto. Lee los archivos principales y describe: estructura de directorios, patron de diseno, tecnologias usadas y flujo de datos."
    }
  }
}

Casos de Uso Practicos

/review — Code Review Automatico

{
  "/review": {
    "description": "Review del ultimo commit",
    "prompt": "Ejecuta git diff HEAD~1 y revisa los cambios. Para cada archivo modificado analiza: 1) Problemas de seguridad 2) Problemas de performance 3) Codigo duplicado 4) Nombres poco descriptivos. Genera un reporte ordenado por severidad."
  }
}

/test — Generar Tests

{
  "/test": {
    "description": "Generar tests para cambios recientes",
    "prompt": "Revisa los archivos modificados con git status. Para cada archivo fuente modificado, genera tests unitarios siguiendo las convenciones existentes del proyecto. Asegurate de cubrir edge cases y caminos de error."
  }
}

/deploy — Verificar antes de Deploy

{
  "/deploy": {
    "description": "Verificaciones pre-deploy",
    "prompt": "Ejecuta las siguientes verificaciones antes del deploy: 1) Corre los tests 2) Verifica que no hay console.log 3) Revisa que no hay secretos hardcodeados 4) Verifica que el build compila sin errores. Reporta el resultado de cada paso."
  }
}

/docs — Generar Documentacion

{
  "/docs": {
    "description": "Documentar funciones sin documentar",
    "prompt": "Busca funciones publicas sin documentacion JSDoc en el directorio src/. Para cada una, agrega documentacion con @param, @returns y @example. No modifiques funciones que ya estan documentadas."
  }
}

/fix — Analizar y Corregir Errores

{
  "/fix": {
    "description": "Analizar errores del build",
    "prompt": "Ejecuta el build del proyecto y analiza cualquier error o warning. Para cada problema: 1) Explica la causa 2) Propone una solucion 3) Implementa el fix si es seguro hacerlo. No hagas cambios que puedan romper funcionalidad existente."
  }
}

Comandos vs Skills

Aunque ambos ayudan a automatizar, tienen propositos diferentes:

Aspecto	Comandos	Skills
Activacion	Explicita con /nombre	Automatica por el agente
Contenido	Un prompt directo	Instrucciones detalladas
Alcance	Una accion especifica	Convenciones reutilizables
Contexto	Se envia como mensaje	Se carga on-demand
Formato	Texto plano en JSON	Markdown con estructura

En la practica, un comando puede complementarse con un skill. Por ejemplo, /test puede ser el trigger y un skill testing puede contener las convenciones detalladas que el agente cargara al ejecutar la tarea.

Ejemplo Completo

Configuracion de tres comandos utiles para un proyecto web con Astro:

{
  "commands": {
    "/check": {
      "description": "Verificar salud del proyecto",
      "prompt": "Ejecuta estos comandos en orden: 1) bun astro check - verifica TypeScript y Astro 2) bun build - verifica que compila 3) Revisa si hay archivos con mas de 200 lineas en src/. Reporta un resumen de cada verificacion."
    },
    "/new-page": {
      "description": "Crear nueva pagina del tutorial",
      "prompt": "Necesito crear una nueva pagina para el tutorial. Preguntame: 1) Nombre del archivo 2) Titulo del capitulo 3) Descripcion breve. Luego crea el archivo con el frontmatter correcto siguiendo el formato de los archivos existentes en la misma coleccion."
    },
    "/optimize": {
      "description": "Optimizar componentes",
      "prompt": "Analiza los componentes en src/components/. Para cada uno revisa: 1) Imports no usados 2) Props sin tipar 3) Logica que podria extraerse 4) Oportunidades de lazy loading. Lista las mejoras ordenadas por impacto."
    }
  }
}

Buenas Practicas

• Prompts claros y acotados: un comando debe hacer una cosa bien
• Incluye instrucciones de seguridad: “no modifiques archivos de configuracion” o “no hagas cambios destructivos”
• Usa nombres cortos: /review es mejor que /hacer-code-review-completo
• Documenta con description: aparece en el autocompletado y ayuda a recordar que hace cada comando
• No dupliques logica de skills: si el prompt necesita instrucciones detalladas, mejor crea un skill
• Commitea la configuracion: opencode.json debe estar en el repositorio para que el equipo comparta los comandos

---

Siguiente: Capitulo 15: Plugins —>