drawio-skill — агентный скилл для создания и сопровождения архитектурных диаграмм

Архитектурная диаграмма обычно кажется простым результатом: есть сервисы, стрелки, базы данных и несколько блоков. Сложность начинается, когда её нужно не просто нарисовать, а поддерживать вместе с кодом, инфраструктурой и документацией. Проект drawio-skill добавляет такой слой автоматизации: агент создаёт редактируемый файл .drawio, проверяет результат, строит несколько представлений одной модели и может обновлять их без потери ручной раскладки.

Это агентский скилл в формате Agent Skills. Он работает с Claude Code, Cursor, Copilot, OpenClaw, Codex, Autohand Code, Hermes и другими совместимыми агентами. Основной сценарий не требует отдельного GUI-сервиса или постоянно работающего демона, но для генерации и экспорта используется desktop CLI draw.io.

Что умеет drawio-skill

Скилл закрывает полный цикл работы с диаграммами: создание, импорт реальных источников, автоматическая раскладка, проверка, синхронизация, анализ и экспорт.

Из текстового запроса он создаёт редактируемую диаграмму. Агент планирует композицию, генерирует XML draw.io, экспортирует черновик в PNG, проверяет его и исправляет наложения, обрезанные подписи и совпадающие маршруты. Предусмотрено до двух автоматических циклов проверки и до пяти итераций с учётом замечаний пользователя.

Поддерживаются 11 готовых категорий диаграмм:

• ERD;
• UML Class и Sequence;
• модель C4;
• архитектура приложения и инфраструктуры;
• диаграммы ML и Deep Learning;
• Flowchart;
• SysML;
• BPMN;
• сетевая топология;
• кросс-функциональные swimlane-диаграммы.

Входом может быть не только текст. Скилл преобразует в нативный .drawio 28 стандартных типов Mermaid, включая mindmap, gantt, timeline, journey, pie, sankey и kanban. Для этого рекомендуется draw.io версии 30 или новее. Фотографию доски или скриншот существующей схемы также можно восстановить в редактируемую диаграмму с сохранением приблизительной исходной композиции.

Импорт архитектуры из реальных источников

Вторая сильная сторона проекта — построение графа из материалов, которые уже описывают систему. Скилл умеет извлекать:

• графы импортов Python, JavaScript, TypeScript, Go и Rust;
• иерархии классов Python;
• конфигурации Terraform, Kubernetes и docker-compose;
• фактическое состояние инфраструктуры из вывода terraform show -json, docker inspect и kubectl get -o json;
• SQL DDL для ER-диаграмм;
• OpenAPI и Swagger с выделением HTTP-методов;
• AsyncAPI для событийной архитектуры;
• Protocol Buffers для схем сообщений и сервисов;
• GraphQL SDL для сущностей и типов;
• GitHub Actions и GitLab CI в виде DAG.

Для облачных ресурсов проект пытается использовать официальные значки AWS, Azure, GCP и Kubernetes. Отдельный поиск по библиотеке draw.io находит точные стили более чем 10 000 фигур, включая Cisco, UML, BPMN и сетевые элементы. Поэтому агенту не приходится угадывать имя встроенной фигуры и получать пустые прямоугольники.

Для приложений с LLM предусмотрен отдельный каталог из 321 логотипа AI-сервисов и 18 марок хранилищ данных. Логотипы могут ссылаться на CDN либо встраиваться в диаграмму как data URI для автономного файла.

Как устроена работа

Базовый сценарий выглядит так:

1. агент проверяет доступные зависимости;
2. планирует структуру и раскладку;
3. создаёт XML draw.io;
4. экспортирует черновик в PNG;
5. анализирует изображение и исправляет визуальные дефекты;
6. показывает результат пользователю;
7. уточняет результат по обратной связи и сохраняет финальный экспорт.

Для реальных источников внутренний pipeline представлен как последовательность извлечения графа, автоматической раскладки и валидации:

python3 scripts/tfimports.py ./infra -o graph.json
python3 scripts/autolayout.py graph.json -o architecture.drawio
python3 scripts/drawiodiff.py v1.drawio v2.drawio -o drift.json
python3 scripts/drawiohtml.py architecture.drawio -o architecture.html

Опциональный Graphviz отвечает за размещение узлов, ортогональную маршрутизацию, группировку модулей и сокращение транзитивных связей. Остальные основные сценарии работают без него. Отдельные движки детерминированно строят sequence-диаграммы с линиями жизни и активациями, а также многостраничные модели C4 с переходами между уровнями.

Архитектурная модель и синхронизация

Проект не ограничивается однократной генерацией. В его основе используется Diagram IR, который отделяет смысл модели и происхождение данных от геометрии. Из одной модели можно строить executive-, system-, deployment-, data-flow- и security-представления.

Команда diagramctl sync обновляет изменившиеся узлы и связи, сохраняя вручную настроенные координаты, стили и аннотации. Удаления по умолчанию остаются доступными для ревью, что снижает риск случайно потерять элементы при синхронизации с новой версией источника.

Для контроля архитектуры предусмотрены правила в YAML или JSON. Они проверяют доступ из интернета к базе данных, циклы, изолированные компоненты, границы доверия и контраст. Правила можно запускать как Diagram-as-Test в CI. Официальный GitHub Action проверяет их в pull request, а отдельное действие показывает визуальный diff.

CLI diagramctl объединяет команды doctor, build, sync, views, query, test, review, whatif, story, publish и transform. Через него можно искать компоненты, владельцев и пути, находить связанные с высокой связностью части системы, моделировать распространение отказа и собирать доступную интерактивную презентацию архитектуры. MCP-сервер нужен только для MCP-хостов; базовые операции выполняются локально через CLI.

Экспорт и визуальная настройка

Готовую диаграмму можно преобразовать в интерактивный HTML с панорамированием, масштабированием и поиском, презентацию PowerPoint, анимированный SVG потоков данных, Mermaid, Markdown, кликабельный runbook или краткое описание для руководства. Есть также timelapse-история изменений и цветной diff, где добавленные элементы выделяются зелёным, удалённые — красным, изменённые — оранжевым.

Скилл предоставляет пресеты default, corporate, handdrawn, colorblind-safe и dark. Пользователь может создать собственный стиль на основе готового .drawio или плоского изображения. После извлечения цветов, фигур, шрифтов и правил соединений проект показывает превью и сохраняет пресет только после подтверждения. Есть отдельные режимы для двуязычных подписей, тепловых карт по метрикам, разведения маршрутов и оформления схемы в стиле метрополитена.

Установка и быстрый старт

На macOS desktop CLI устанавливается через Homebrew:

brew install --cask drawio
drawio --version

Для Windows и Linux доступны пакеты на странице релизов draw.io Desktop. Linux-системе для headless-рендеринга обычно нужен xvfb. Затем скилл можно установить глобально для совместимого агента:

npx skills add Agents365-ai/drawio-skill -g

Репозиторий также клонируется вручную:

git clone https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill

После установки достаточно дать агенту обычное описание системы. Например, можно попросить создать архитектуру интернет-магазина с мобильным и веб-клиентами, API Gateway, сервисами авторизации, заказов, каталога и платежей, Kafka, хранилищами, Redis и внешним платёжным API. Скилл сам выберет представление, подготовит редактируемый .drawio и предложит следующие итерации.

Проект распространяется по лицензии MIT. Он полезен архитекторам, backend- и platform-инженерам, командам, которые хранят диаграммы рядом с кодом, и разработчикам агентских workflow, которым нужен воспроизводимый результат вместо одноразового изображения.