Как закодировать друга и не спиться: настройка OpenCode через /add и /help

Проблема: много инструментов, ничего не помню

Владимир Бандов, backend-разработчик Домклика, долгое время отрицал нужность агентов. Когда всё же попробовал OpenCode Desktop, столкнулся с жёсткой реальностью: множество Skills, MCP, Permissions, несколько конфигураций одновременно. Агент постоянно делал лишние шаги, придумывал и реализовывал то, что не входило в задачу. Первые полчаса настройка шла гладко, но вскоре стало ясно: нужно запомнить, какой навык для чего, и объяснять агенту логику — сначала план, потом доступы, конфигурации, команды в терминале. После пары свободных вечеров автор нашёл ленивый подход. Расходует больше токенов, но работает как надо: агент помощник, а не полноценный разработчик, требующий присмотра.

Схема: четыре файла и одна справка

Решение строится на минималистичной структуре в ~/.config/opencode/: файл справки HELP.md, две папки с навыками и командами.

Структура:

• HELP.md — единый реестр, который читают обе команды вместо дорогого сканирования
• skills/environment-manager/SKILL.md — основной навык для добавления новых возможностей
• skills/opencode-help/SKILL.md — вспомогательный навык
• commands/add.md — команда для добавления
• commands/help.md — команда для справки

/add: скажи желание, не название пакета

Команда /add передаёт запрос пользователя навыку environment-manager. Порядок фиксирован и строг.

Шаги выполнения:

1. Проверка: решается ли задача уже установленными skills, commands или MCP?
2. Таблица сравнения вариантов с колонками: Вариант, Тип, Что получу, Доступы/секреты, Риски, Context/token overhead, Рекомендация
3. Явный выбор одного варианта с объяснением
4. Полный текст файлов и unified diff, точные пути, список затронутых файлов
5. Обновление HELP.md: дата подготовки и затронутые skills, commands, MCP, permissions
6. Ничего не записывается без явного подтверждения пользователя

Запреты: никакие изменения без подтверждения; не менять opencode.jsonc, не устанавливать пакеты, не подключать MCP, не создавать OAuth/PAT, не читать секреты, токены, .env, SSH-ключи, service.json.

Внутри environment-manager определены жёсткие границы: используй существующие skills (general-engineering, technical-research, prompt-engineering, token-efficient-workflow, project-learning) только по назначению. Оцени сторонние MCP и plugins по: maintainer, официальный источник, требуемые токены, permissions, локальность/сеть, active maintenance, supply-chain risk, context/token overhead, совместимость с OpenCode V2.

Permissions по умолчанию — ask. Write access к GitHub, БД, почте, хранилищам, Sentry, Jira, Docker, облаку — только после отдельного явного запроса.

/help: читать готовое вместо аудита

Первая версия /help сканировала навыки, команды и разрешения каждый раз — медленно и дорого. Вторая просто читает HELP.md.

Команда отвечает в три шага: сначала использует релевантный раздел HELP.md; если недостаточно — ищет ответ в безопасных read-only источниках и официальной документации OpenCode; явно указывает, что HELP.md — подготовленный реестр, не live-runtime гарантия. Если реестр и факты расходятся, показывает расхождение и предлагает обновить HELP.md через /add.

Как это работает

Пользователь: «/add хочу GitHub интеграцию». Environment-manager проверяет, что уже есть, предлагает таблицу вариантов (skill vs MCP vs plugin), явно выбирает лучший, показывает полный текст новых файлов и diff, обновляет HELP.md, ждёт подтверждения. Ничего не меняется автоматически.

Пользователь: «/help что у меня есть?». Команда читает HELP.md и выводит список подключённых skills, commands, MCP, permissions. Указывает, что информация из реестра, не live.

Результат: Владимир Бандов избежал главной ошибки — не пытался запомнить конфигурацию и не возложил её на агента слепо. Агент предлагает план, показывает diff, ждёт подтверждения. Две команды, один реестр, простые правила. Больше токенов, но значительно меньше мук.