Cómo programar con un amigo de IA sin volverte loco: configurar OpenCode con /add y /help

El problema: muchas herramientas, no recuerdo nada

Vladimir Bandov, desarrollador backend de Domclick, negó durante mucho tiempo la necesidad de usar agentes. Cuando finalmente probó OpenCode Desktop, se topó con una realidad dura: multitud de Skills, MCP, Permissions y varias configuraciones a la vez. El agente daba constantemente pasos innecesarios, inventaba y ejecutaba cosas que no formaban parte de la tarea.

La primera media hora de configuración transcurrió sin problemas, pero pronto quedó claro: había que recordar qué skill servía para qué y explicarle al agente la lógica cada vez —primero el plan, luego los accesos, las configuraciones, los comandos de terminal—. Tras un par de noches libres, el autor encontró un enfoque más perezoso. Consume más tokens, pero funciona como debería: el agente como ayudante, no como un desarrollador pleno que necesita vigilancia.

El esquema: cuatro archivos y una referencia

La solución se basa en una estructura minimalista dentro de ~/.config/opencode/: un archivo de ayuda, HELP.md, y dos carpetas con skills y comandos.

Estructura:

• HELP.md — un registro único que ambos comandos leen en lugar de hacer un escaneo costoso
• skills/environment-manager/SKILL.md — la skill principal para añadir nuevas funciones
• skills/opencode-help/SKILL.md — una skill auxiliar
• commands/add.md — el comando de añadir
• commands/help.md — el comando de ayuda

/add: expresa tu deseo, no el nombre de un paquete

El comando /add pasa la solicitud del usuario a la skill environment-manager. El orden de ejecución es fijo y estricto.

Pasos de ejecución: 1. Comprobar si la tarea ya puede resolverse con skills, commands o MCP ya instalados 2. Una tabla comparativa de opciones con columnas: Opción, Tipo, Qué obtengo, Accesos/secretos, Riesgos, Sobrecarga de contexto/tokens, Recomendación 3. Elección explícita de una opción con su justificación 4. Texto completo de los archivos y un diff unificado, rutas exactas, lista de archivos afectados 5. Actualización de HELP.md: fecha de preparación y skills, commands, MCP y permisos afectados 6. No se escribe nada sin confirmación explícita del usuario

Prohibiciones: ningún cambio sin confirmación; no modificar opencode.jsonc, no instalar paquetes, no conectar MCP, no crear OAuth/PAT, no leer secretos, tokens, .env, claves SSH, service.json.

Dentro de environment-manager hay límites estrictos: usar las skills existentes (general-engineering, technical-research, prompt-engineering, token-efficient-workflow, project-learning) solo para su propósito. Evaluar los MCP y plugins de terceros según: mantenedor, fuente oficial, tokens requeridos, permisos, localidad/red, mantenimiento activo, riesgo de cadena de suministro, sobrecarga de contexto/tokens, compatibilidad con OpenCode V2.

Los permisos por defecto son del tipo ask. El acceso de escritura a GitHub, bases de datos, correo, almacenamiento, Sentry, Jira, Docker, la nube, solo se concede tras una solicitud explícita por separado.

/help: leer lo ya preparado en lugar de auditar

La primera versión de /help escaneaba skills, commands y permisos cada vez: lento y costoso. La segunda simplemente lee HELP.md.

El comando responde en tres pasos: primero usa la sección relevante de HELP.md; si no es suficiente, busca la respuesta en fuentes seguras de solo lectura y en la documentación oficial de OpenCode; indica explícitamente que HELP.md es un registro preparado, no una garantía en tiempo real. Si el registro y los hechos no coinciden, muestra la discrepancia y propone actualizar HELP.md mediante /add.

Cómo funciona en la práctica

Usuario: «/add quiero integración con GitHub». El environment-manager comprueba qué hay ya disponible, propone una tabla de opciones (skill vs. MCP vs. plugin), elige explícitamente la mejor, muestra el texto completo de los nuevos archivos y el diff, actualiza HELP.md y espera confirmación. Nada cambia automáticamente.

Usuario: «/help ¿qué tengo?». El comando lee HELP.md y muestra la lista de skills, commands, MCP y permisos conectados. Aclara que la información proviene del registro, no del estado en vivo.

Resultado: Vladimir Bandov evitó el error principal: no intentó memorizar la configuración él mismo ni se la delegó ciegamente al agente. El agente propone un plan, muestra el diff y espera confirmación. Dos comandos, un registro, reglas simples. Más tokens, pero muchísimo menos sufrimiento.