Visual Explainer — скилл, который превращает вывод терминала в читаемые HTML-страницы
📂 Исходный код на GitHubСкилл для кодинг-агентов: рисует диаграммы, визуальные ревью диффов, слайды и видео как самодостаточные HTML-страницы вместо ASCII-арта в терминале. Работает с Claude Code, Pi, Codex CLI, OpenCode, Cursor, Antigravity и MCP-хостами.
Visual Explainer — агентный скилл, который превращает сложный вывод терминала в оформленные HTML-страницы, которые действительно хочется читать. Попросите агента нарисовать схему архитектуры, сделать ревью диффа или сравнить требования с планом. Вместо ASCII-арта и таблиц из псевдографики он соберёт самодостаточную HTML-страницу и откроет её в браузере.
> draw a diagram of our authentication flow
> /diff-review
> /plan-review ~/docs/refactor-plan.mdЗачем это нужно
Любой кодинг-агент по умолчанию рисует диаграммы текстом: рамки из псевдографики, выравнивание пробелами, стрелки из символов. Для схемы из трёх блоков это работает. Всё, что сложнее, превращается в нечитаемую кашу.
С таблицами ещё хуже. Попросите агента сравнить 15 требований с планом — и вы получите стену из вертикальных черт и дефисов, которая ломается при переносе строк. Данные там есть, но читать их больно.
Этот скилл решает проблему. На странице настоящая типографика, тёмные и светлые темы, диаграммы, нарисованные от руки, которые анимируются и реагируют на читателя. Обычному режиму скилла не нужны сборка и зависимости — только браузер. Необязательные MCP-сервер и экспорт в PPTX ставят несколько небольших Node-пакетов.
Живой пример — очередь задач, нарисованная как конечный автомат и проигранная по одному событию: маршрут каждого события подсвечивается, задачи копятся в очереди и разбираются, и на каждом шаге написано, почему он произошёл.
Команды
| Команда | Что делает |
|---|---|
/generate-web-diagram |
Страница с диаграммами, данными или объяснением любой темы |
/generate-visual-plan |
План внедрения, на который отвечают прямо на странице: изменение нарисовано, решения показаны с вариантами по умолчанию, готовый ответ вставляется обратно в чат |
/generate-slides |
Презентация из слайдов журнального качества |
/generate-video |
MP4-видео с озвучкой или запись обхода живого веб-приложения |
/diff-review |
Визуальное ревью диффа со сравнением архитектуры и код-ревью |
/plan-review |
Проверка плана по кодовой базе: у каждой находки показаны доказательства и исправление, которое принимают или отклоняют прямо на странице |
/project-recap |
Снимок картины проекта, чтобы вернуться к нему после перерыва |
/compare |
Два и больше вариантов бок о бок с рекомендацией; выбор делается на странице и возвращается агенту |
/fact-check |
Проверка документа на соответствие реальному коду |
/state-machine |
Конечный автомат, нарисованный прямо из кода: страница проходит по каждому состоянию и показывает забытые состояния, события, которые никогда не срабатывают, тупики и нарушенные правила |
Есть и автоматическое срабатывание: когда агент собирается вывести в терминал большую таблицу (4 строки и больше или 3 колонки и больше), скилл вместо этого отрисует HTML-страницу.
Установка
Каноническая папка скилла — plugins/visual-explainer/. Её копируют в каталог скиллов конкретного агента. У каждой среды свой путь:
| Среда | Как поставить |
|---|---|
| Claude Code | Плагин из маркетплейса |
| Pi | pi install git:github.com/nicobailon/visual-explainer |
| Codex CLI | Скопировать в ~/.codex/skills/visual-explainer |
| OpenCode | Скопировать в ~/.config/opencode/skill/visual-explainer |
| Cursor | Скопировать в ~/.cursor/skills/ или .cursor/skills/ |
| Antigravity CLI | Скопировать в ~/.gemini/antigravity-cli/skills/ или .agents/skills/ |
| MCP-хосты | Локальный stdio-сервер visual-explainer-mcp |
| VS Code Copilot | Инструкции из configs/copilot/AGENTS.md |
| Agent Plugins | Плагин 1.0.0, корень репозитория — сам плагин |
Для Claude Code:
/plugin marketplace add nicobailon/visual-explainer
/plugin install visual-explainer@visual-explainer-marketplaceДля Pi:
pi install git:github.com/nicobailon/visual-explainerДля остальных сред клонируйте репозиторий и скопируйте plugins/visual-explainer/ в каталог скиллов. Готовые команды для каждой среды, включая сценарии для Windows PowerShell, собраны в README репозитория.
Вместе со скиллом ставятся шаблоны команд: их копируют в каталог промптов среды (например, ~/.codex/prompts/), чтобы вызывать /diff-review, /plan-review и другие как слэш-команды. В Claude Code команды получают префикс пространства имён: /visual-explainer:diff-review.
В Pi скилл регистрирует ещё и нативный инструмент visual_explainer с двумя действиями: prepare — спланировать визуальное объяснение после большого плана, архитектуры, диффа или внедрения, и render — собрать и открыть страницу.
Как это устроено
Результат по умолчанию пишется в ~/.agent/diagrams/имя.html и открывается в браузере. Агент пишет короткий исходник имя.src.html, который подключает общий набор стилей и скриптов. Рендерер собирает из исходника полную страницу и оставляет исходник для мелких правок. Если в системе есть Chrome и playwright-core, рендерер дополнительно проверяет страницу в браузере и сохраняет лист миниатюр: первый экран, все схемы, все шаги. Агент смотрит на этот лист вместо того, чтобы делать собственные скриншоты. По запросу агент пишет и имя.md — текстовую версию страницы для чтения самим агентом.
Страницы строятся по принципу «сначала картинка»: первый экран показывает ответ в виде рисунка и одного предложения. У каждой страницы одно из четырёх оформлений — Instrument для ревью и метрик, Blueprint для архитектуры, Paper для объяснения концепций, Editorial для пересказов и презентаций. У каждого оформления свои шрифты, проверенная на контраст палитра и общая типографская шкала. Термины в тексте и части схемы подсвечиваются вместе при наведении. Диаграммы рисуются от руки как встроенный SVG, поэтому совпадают со стилем страницы и умеют пошагово проигрывать процесс. Mermaid подключается только по явной просьбе. В таблицах — статусные бейджи, у метрик — столбики и мини-графики, текст пишется в стиле упрощённого технического английского (Simplified Technical English).
Темы оформления
Попросите переключаемые темы или назовите палитру — на странице появится переключатель: цветные точки для палитры и кнопки «Aa» для пары шрифтов, всё меняется на лету.
"explain this pipeline, use Gruvbox"
"diagram the auth flow, let me switch themes"В комплекте одиннадцать палитр: Dracula, Nord, One Dark, Catppuccin Mocha, Tokyo Night, Gruvbox Dark и Synthwave '84 — тёмные; Solarized Light, GitHub Light, Catppuccin Latte и Gruvbox Light — светлые. Диаграммы рисуются цветами текущей темы, поэтому всегда совпадают с оформлением. Палитру и шрифты по умолчанию задают в файле visual-explainer.config.md. Сам переключатель — опция: страницы, которые его не просят, получают одну палитру и пару шрифтов, подобранную под содержание.
MCP-сервер и экспорт
Для MCP-хостов в репозитории есть локальный stdio-сервер visual-explainer-mcp с двумя инструментами: visual_explainer_prepare — спланировать визуальное объяснение, и visual_explainer_render_html — отрисовать страницу. Сервер не обращается к LLM, не поднимает HTTP-сервер и не пишет за пределами своей выходной папки. По умолчанию это ~/.agent/diagrams/, путь переопределяется переменной VISUAL_EXPLAINER_OUTPUT_DIR.
Готовую HTML-презентацию можно выгрузить в .pptx утилитой visual-explainer-pptx. Экспорт статичный и упрощённый: он переносит заголовки, текст, списки, простые таблицы и блоки кода, но не анимации и не живые диаграммы. Источник истины — HTML-версия. Есть и видео: команда /generate-video пишет видеоряд, а рендерер visual-explainer-video записывает его в MP4 1080p покадрово — с озвучкой, если задан ключ речевого API, или с субтитрами без него.
Ограничения
- Сгенерированный HTML переносимый и самодостаточный, но автооткрытие зависит от среды, доступа к браузеру и правил песочницы.
- Экспорт в PPTX — статичная попытка переноса; для полного визуального соответствия используйте HTML-версию.
- Качество результата зависит от возможностей модели.
Детали
Лицензия — MIT. Идеи позаимствованы у скилла frontend-design от Anthropic и проекта interface-design. Mermaid-диаграммы рисует Pele из Obsidian (MIT) — он включён в комплект.