Comment coder avec un ami sans sombrer dans la configuration : paramétrer OpenCode via /add et /help

Le problème : trop d'outils, plus rien en mémoire

Vladimir Bandov, développeur backend chez Domclick, a longtemps nié l'utilité des agents. Lorsqu'il a finalement essayé OpenCode Desktop, il a été confronté à une réalité difficile : une multitude de Skills, de MCP, de Permissions, et plusieurs configurations en même temps. L'agent multipliait sans cesse les étapes superflues, inventant et réalisant des choses hors du périmètre de la tâche.

Les trente premières minutes de configuration se sont déroulées sans accroc, mais il est vite apparu qu'il fallait retenir quel skill servait à quoi, et expliquer à l'agent la logique à suivre — d'abord le plan, puis les accès, les configurations, les commandes dans le terminal. Après quelques soirées libres, l'auteur a trouvé une approche paresseuse. Elle consomme plus de tokens, mais fonctionne comme il faut : l'agent reste un assistant, pas un développeur à part entière nécessitant une surveillance.

Le schéma : quatre fichiers et une seule aide

La solution repose sur une structure minimaliste dans ~/.config/opencode/ : un fichier d'aide HELP.md, et deux dossiers contenant des skills et des commandes.

Structure :

• HELP.md — le registre unique, lu par les deux commandes au lieu d'un scan coûteux
• skills/environment-manager/SKILL.md — le skill principal pour ajouter de nouvelles fonctionnalités
• skills/opencode-help/SKILL.md — un skill auxiliaire
• commands/add.md — la commande d'ajout
• commands/help.md — la commande d'aide

/add : exprime ton souhait, pas le nom d'un paquet

La commande /add transmet la requête de l'utilisateur au skill environment-manager. L'ordre des opérations est fixe et strict.

Étapes d'exécution : 1. Vérification : la tâche peut-elle déjà être résolue par des skills, commands ou MCP déjà installés ? 2. Un tableau comparatif des options, avec les colonnes suivantes : Option, Type, Ce que j'obtiens, Accès/secrets, Risques, Surcharge de contexte/tokens, Recommandation 3. Un choix explicite d'une seule option, avec justification 4. Le texte intégral des fichiers et un diff unifié, avec les chemins exacts et la liste des fichiers concernés 5. Mise à jour de HELP.md : date de préparation et skills, commands, MCP, permissions concernés 6. Rien n'est enregistré sans confirmation explicite de l'utilisateur

Interdictions : aucune modification sans confirmation ; interdiction de modifier opencode.jsonc, d'installer des paquets, de connecter des MCP, de créer des OAuth/PAT, de lire des secrets, des tokens, des fichiers .env, des clés SSH ou service.json.

Au sein d'environment-manager, des limites strictes sont fixées : utiliser les skills existants (general-engineering, technical-research, prompt-engineering, token-efficient-workflow, project-learning) uniquement pour l'usage prévu. Évaluer les MCP et plugins tiers selon : le mainteneur, la source officielle, les tokens requis, les permissions, le fonctionnement local/réseau, la maintenance active, le risque de chaîne d'approvisionnement, la surcharge de contexte/tokens, la compatibilité avec OpenCode V2.

Les permissions sont par défaut en mode ask. L'accès en écriture à GitHub, aux bases de données, à la messagerie, aux stockages, à Sentry, Jira, Docker, au cloud — n'est accordé qu'après une demande explicite et distincte.

/help : lire du prêt-à-l'emploi plutôt qu'un audit

La première version de /help scannait les skills, les commands et les permissions à chaque appel — lent et coûteux. La seconde version se contente de lire HELP.md.

La commande répond en trois étapes : elle utilise d'abord la section pertinente de HELP.md ; si cela ne suffit pas, elle cherche la réponse dans des sources sécurisées en lecture seule et dans la documentation officielle d'OpenCode ; elle indique explicitement que HELP.md est un registre préparé, et non une garantie en temps réel. Si le registre et les faits diffèrent, elle signale l'écart et propose de mettre à jour HELP.md via /add.

Comment ça marche en pratique

Utilisateur : « /add je veux une intégration GitHub ». L'environment-manager vérifie ce qui existe déjà, propose un tableau d'options (skill contre MCP contre plugin), choisit explicitement la meilleure, affiche le texte intégral des nouveaux fichiers et le diff, met à jour HELP.md, puis attend la confirmation. Rien ne change automatiquement.

Utilisateur : « /help qu'est-ce que j'ai ? ». La commande lit HELP.md et affiche la liste des skills, commands, MCP et permissions connectés. Elle précise que l'information provient du registre, pas du temps réel.

Résultat : Vladimir Bandov a évité l'erreur principale — il n'a pas essayé de retenir sa configuration par cœur, et ne l'a pas non plus confiée aveuglément à l'agent. L'agent propose un plan, montre un diff, attend une confirmation. Deux commandes, un registre, des règles simples. Plus de tokens, mais nettement moins de tracas.